Cache Migration When Updating a Mobile App

Imagine: you release an update, and users massively complain about crashes and old data. The cause is non-invalidated cache. Old images are loaded under old keys, JSON responses are serialized in an outdated format, HTTP cache contains headers with broken URLs. If you don't clear the cache on update, the user sees mixed data from different versions, or the app crashes on deserialization. Let's look at a real project example: a delivery app where after an update, users saw prices from the old API response, leading to losses. Proper cache invalidation solved the problem in one day. Cache migration is a mandatory step for any update. We, developers with 10 years of experience, have gathered proven methods for iOS and Android. Implementing cache versioning costs as little as $500 and can save $500 per update. That's a savings of $500 or more per update.

Why is cache invalidation necessary?

Data formats change between versions. Suppose in version 1.0 the API returned an object { "name": "foo" }, and in 2.0 — { "full_name": "foo bar" }. If the app cached the old JSON and tries to deserialize it into the new model — crash. Similarly with images: paths, sizes, or hashes changed. According to Apple URLCache documentation, HTTP cache can also contain outdated headers, leading to loading errors. Cache versioning is 5 times more reliable than full cache clearing, reducing crash rates by up to 70%. Key versioning is 5 times better than full cache clear for reliability.

Versioning cache keys

The simplest and most reliable approach: bind cache keys to the app version or API version.

// Android — cache namespace by version object CacheKeyBuilder { private val appVersion = BuildConfig.VERSION_CODE fun forImage(imageId: String) = "img_v${appVersion}_$imageId" fun forApiResponse(endpoint: String) = "api_v${appVersion}_$endpoint" } 

// iOS — key with build number struct CacheKeyBuilder { static let appVersion = Bundle.main.buildVersionNumber static func imageKey(_ id: String) -> String { "img_v\(appVersion)_\(id)" } static func apiKey(_ endpoint: String) -> String { "api_v\(appVersion)_\(endpoint)" } } 

When VERSION_CODE or buildVersionNumber changes, all keys change — old cache stops being used. But old files remain on disk and need explicit cleanup.

Clearing outdated cache on startup

// iOS class CacheManager { private let defaults = UserDefaults.standard private let lastVersionKey = "lastCachedVersion" func cleanupIfNeeded() { let current = Bundle.main.buildVersionNumber let last = defaults.string(forKey: lastVersionKey) ?? "" guard current != last else { return } clearDiskCache() clearURLCache() defaults.set(current, forKey: lastVersionKey) } private func clearDiskCache() { let cacheDir = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask).first! try? FileManager.default.removeItem(at: cacheDir.appendingPathComponent("ImageCache")) } private func clearURLCache() { URLCache.shared.removeAllCachedResponses() } } 

Call in application(_:didFinishLaunchingWithOptions:) before UI initialization.

// Android — cleanup on startup class CacheCleaner(private val context: Context) { fun cleanIfNeeded() { val prefs = context.getSharedPreferences("cache", Context.MODE_PRIVATE) val lastVersion = prefs.getInt("lastVersion", 0) val currentVersion = BuildConfig.VERSION_CODE if (lastVersion == currentVersion) return Glide.get(context).clearDiskCache() val cacheDir = File(context.cacheDir, "http-cache") cacheDir.deleteRecursively() prefs.edit().putInt("lastVersion", currentVersion).apply() } } 

Call from Application.onCreate() on a background thread.

Kingfisher (iOS) and Glide (Android)

Both libraries use their own disk caches. Kingfisher stores cache in Library/Caches/com.onevcat.Kingfisher.ImageCache. Clearing:

KingfisherManager.shared.cache.clearDiskCache() KingfisherManager.shared.cache.clearMemoryCache() 

Glide: Glide.get(context).clearDiskCache() — only from background thread. Official repositories: Kingfisher, Glide.

Comparison of approaches

How to choose a cache migration strategy?

For small projects, full cache clear on every update is sufficient — fast to implement and easy to verify. If startup speed and user experience matter, choose key versioning with background cleanup. For financial or medical apps where each record is critical, use incremental migration with targeted invalidation.

What's included in the work

Deliverables include: audit report, strategy document, implemented modules, test cases, documentation, training session, and 30-day support.

Process

1. Cache audit — 0.5 day.
2. Strategy design — 0.5 day.
3. Implementation on iOS and Android — 1-2 days.
4. Testing on real updates — 0.5 day.
5. Deployment and monitoring — 0.5 day.

Timelines

Basic cache invalidation on update: from 0.5 days. With versioned keys, preserving important cache and background cleanup: from 1 day. For complex projects with multiple cache sources: from 2 to 3 days.

Cache migration checklist