fix: evict image from cache on error during image loading

[LeLunZ]

Description

In my recent testing for PR #25984 I noticed that images that failed loading, could never be loaded correctly. In the timeline they always showed up as Thumbhash, and the Thumbnail never finished loading. Even when switching to albums and then going back to the asset viewer.

Or if a thumbnail was already cached/working, I clicked on it. The asset viewer loaded, and for some reason the actual image request failed, the thumbnail was shown instead (as intended).
When closing the asset viewer, and clicking on the same image again, it doesn't start show the image thumbnail like before, but a grey background.

The Issue:
If in the CancellableImageProviderMixin.loadRequest the await request.load(decode); throws for whatever reason, the error is propagated to the listeners but the cache for the entry is never cleared.

That means, ImageProvider.resolve will actually resolve to that erroring cached ImageStreamCompleter and the cache entry is never cleared.

The thing is from my understanding await request.load(decode) could throw for a lot of networking reasons, so I think its better to clear the cache from this entry, and try to load the image again if it is requested again.

In this PR: When an error happens while loading the image, we remove it from the cache, and then the error is propagated like before.

Also, I am not sure but this could help with issues such as #25662 ?

How Has This Been Tested?

• this can be tested really well if you clear the immich cache from the settings and then turn of wifi/cellular

Checklist:

• I have performed a self-review of my own code
• I have made corresponding changes to the documentation if applicable
• I have no unrelated changes in the PR.
• I have confirmed that any new dependencies are strictly necessary.
• I have written tests for new code (if applicable)
• I have followed naming conventions/patterns in the surrounding code
• All code in src/services/ uses repositories implementations for database calls, filesystem operations, etc.
• All code in src/repositories/ is pretty basic/simple and does not have any immich specific logic (that belongs in src/services/)

Please describe to which degree, if any, an LLM was used in creating this pull request.

[Copilot]

Pull request overview

Fixes a Flutter image-caching edge case in the mobile app where a failed image load could leave an erroring ImageStreamCompleter stuck in the ImageCache, preventing subsequent successful reloads for the same image provider key.

Changes:

• Evict the ImageProvider key from PaintingBinding.instance.imageCache when request.load(decode) throws.
• Preserve existing behavior by rethrowing the error to current listeners while ensuring future resolves can retry.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[LeLunZ]

Also from the RemoFullImageProvider._codec:

if the loadOriginal toggle was enabled, and the thumbnail would fail for whatever reason, the code never tries to load the original image. I am not sure how likely it would be that a thumbnail fails, but the original image would work. But thats also something I noticed.

Stream<ImageInfo> _codec(RemoteFullImageProvider key, ImageDecoderCallback decode) async* {
    yield* initialImageStream();

    if (isCancelled) {
      PaintingBinding.instance.imageCache.evict(this);
      return;
    }

    final headers = ApiService.getRequestHeaders();
    final previewRequest = request = RemoteImageRequest(
      uri: getThumbnailUrlForRemoteId(key.assetId, type: AssetMediaSize.preview, thumbhash: key.thumbhash),
      headers: headers,
    );
    yield* loadRequest(previewRequest, decode);

    if (assetType != AssetType.image || !AppSetting.get(Setting.loadOriginal)) {
      return;
    }

    if (isCancelled) {
      PaintingBinding.instance.imageCache.evict(this);
      return;
    }

    final originalRequest = request = RemoteImageRequest(uri: getOriginalUrlForRemoteId(key.assetId), headers: headers);
    yield* loadRequest(originalRequest, decode);
  }

[mertalev]

If in the CancellableImageProviderMixin.loadRequest the await request.load(decode); throws for whatever reason, the error is propagated to the listeners but the cache for the entry is never cleared.

That's odd, I assumed it isn't cached if there's an error.

[LeLunZ]

@mertalev I also thought that but when I checked the putIfAbsent Method of the ImageCache I noticed that only a normal ImageStreamListener is attached, and no error listener.

And also in the ImageStreamCompleter.reportError method, it only gets all error listeners and triggers the callback.

So on an error the entry is sadly not automatically evicted from cache

---

Too my understanding:

The ImageCache actually caches the ImageStreamCompleter.
And Resolver.resolve will always directly put the new ImageStreamCompleter into the cache.

First it will be in the pending state, and if a first image was emitted it will be moved to "Live" or "normal" cache state.
And there is no specific handling too what happens, if an ImageStreamCompleter reports an error.