fix: keep cache info of removed files when another file cannot be deleted (#541)

* fix: wait for cached files to be removed before deleting their cache info

The cleanup started removing files without waiting and then deleted the
cache info right away, so the cache info could be gone while the files
were still on disk. If the app was killed in between, those files were
left with nothing referencing them.

The cleanup now waits for the file removals first. The cache info of a
file that could not be removed is kept, so the next cleanup retries it.

* fix: keep cache info only of files that could not be removed

Move the partial-failure handling into _removeCachedFile so cleanup,
emptyCache and removeCachedFile all delete the cache info of removed files
and keep only the failed one. A failing deleteAll is logged instead of
replacing the file removal error.

---------

Co-authored-by: Jonathan Unsworth <17317065+junsworth@users.noreply.github.com>

Author: junsworth

flutter_cache_manager/CHANGELOG.md

@@ -1,3 +1,7 @@
+## [3.4.7] - 2026-10-28
+
+* Keeps cache cleanup going when a cached file cannot be deleted: the cache info of the other removed files is still deleted, and only the failed file's cache info is kept so the next cleanup retries it.
+
 ## [3.4.6] - 2026-10-27
 
 * Catches unhandled asynchronous errors when updating cache-hit metadata and during scheduled cleanup in `CacheStore` ([#535](https://github.com/Baseflow/flutter_cache_manager/issues/535)).

flutter_cache_manager/lib/src/cache_store.dart

@@ -198,34 +198,48 @@ class CacheStore {
   }
 
   Future<void> _cleanupCache() async {
-    final toRemove = <int>[];
+    final started = <int>{};
+    final removed = <int>[];
     final provider = await _cacheInfoRepository;
+    final removals = <Future<void>>[];
 
     final overCapacity = await provider.getObjectsOverCapacity(_capacity);
-    final futures = <Future>[];
     for (final cacheObject in overCapacity) {
-      futures.add(_removeCachedFile(cacheObject, toRemove));
+      removals.add(
+        _removeCachedFile(cacheObject, started: started, removed: removed),
+      );
     }
 
     final oldObjects = await provider.getOldObjects(_maxAge);
     for (final cacheObject in oldObjects) {
-      futures.add(_removeCachedFile(cacheObject, toRemove));
+      removals.add(
+        _removeCachedFile(cacheObject, started: started, removed: removed),
+      );
     }
 
-    await Future.wait(futures);
-    await provider.deleteAll(toRemove);
+    await _deleteCacheInfoOfRemoved(
+      provider: provider,
+      removals: removals,
+      removed: removed,
+    );
   }
 
   Future<void> emptyCache() async {
     final provider = await _cacheInfoRepository;
-    final toRemove = <int>[];
+    final started = <int>{};
+    final removed = <int>[];
     final allObjects = await provider.getAllObjects();
-    var futures = <Future>[];
+    final removals = <Future<void>>[];
     for (final cacheObject in allObjects) {
-      futures.add(_removeCachedFile(cacheObject, toRemove));
+      removals.add(
+        _removeCachedFile(cacheObject, started: started, removed: removed),
+      );
     }
-    await Future.wait(futures);
-    await provider.deleteAll(toRemove);
+    await _deleteCacheInfoOfRemoved(
+      provider: provider,
+      removals: removals,
+      removed: removed,
+    );
   }
 
   void emptyMemoryCache() {
@@ -234,18 +248,61 @@ class CacheStore {
 
   Future<void> removeCachedFile(CacheObject cacheObject) async {
     final provider = await _cacheInfoRepository;
-    final toRemove = <int>[];
-    await _removeCachedFile(cacheObject, toRemove);
-    await provider.deleteAll(toRemove);
+    final removed = <int>[];
+    final removal = _removeCachedFile(
+      cacheObject,
+      started: <int>{},
+      removed: removed,
+    );
+    await _deleteCacheInfoOfRemoved(
+      provider: provider,
+      removals: [removal],
+      removed: removed,
+    );
+  }
+
+  /// Waits for [removals] and then deletes the cache info of the files in
+  /// [removed], even when some removals failed.
+  Future<void> _deleteCacheInfoOfRemoved({
+    required CacheInfoRepository provider,
+    required List<Future<void>> removals,
+    required List<int> removed,
+  }) async {
+    Object? removalError;
+    StackTrace? removalStack;
+    try {
+      await Future.wait(removals);
+    } catch (e, s) {
+      removalError = e;
+      removalStack = s;
+    }
+
+    try {
+      await provider.deleteAll(removed);
+    } catch (e, s) {
+      if (removalError == null) rethrow;
+      cacheLogger.log(
+        'CacheStore: Failed to delete cache info with error:\n$e\n$s',
+        CacheManagerLogLevel.warning,
+      );
+    }
+
+    if (removalError != null) {
+      Error.throwWithStackTrace(removalError, removalStack!);
+    }
   }
 
+  /// Adds the id to [removed] only once the file is gone, so the cache info of
+  /// a file that could not be deleted is kept and retried. [started] stops the
+  /// same object from being removed twice.
   Future<void> _removeCachedFile(
-    CacheObject cacheObject,
-    List<int> toRemove,
-  ) async {
-    if (toRemove.contains(cacheObject.id)) return;
+    CacheObject cacheObject, {
+    required Set<int> started,
+    required List<int> removed,
+  }) async {
+    final id = cacheObject.id!;
+    if (!started.add(id)) return;
 
-    toRemove.add(cacheObject.id!);
     if (_memCache.containsKey(cacheObject.key)) {
       _memCache.remove(cacheObject.key);
     }
@@ -260,6 +317,7 @@ class CacheStore {
         // File has already been deleted. Do nothing #184
       }
     }
+    removed.add(id);
   }
 
   bool memoryCacheContainsKey(String key) {

flutter_cache_manager/pubspec.yaml

@@ -1,6 +1,6 @@
 name: flutter_cache_manager
 description: Generic cache manager for flutter. Saves web files on the storages of the device and saves the cache info using sqflite.
-version: 3.4.6
+version: 3.4.7
 homepage: https://github.com/Baseflow/flutter_cache_manager
 topics:
   - cache