The `maxByteSize` of the `ImageCache` is no longer automatically made larger to accommodate large images.
Original behavior
Previously, when loading images into the `ImageCache` that had larger byte sizes than the `ImageCache`'s `maxByteSize`, Flutter permanently increased the `maxByteSize` value to accommodate those images. This logic sometimes led to bloated `maxByteSize` values that made working in memory-limited systems more difficult.
New behavior
The following "before" and "after" pseudocode demonstrates the changes made to the `ImageCache` algorithm:
- Who is affected
- Applications and packages relying on the previous behaviour or signature. Code that uses ImageCache, ImageCache.maxByteSize.
- Practical impact
- Behaviour or API differences that can break builds or change runtime behaviour.
- What action should I take?
- Follow the official migration guide below, update affected call sites, run `dart fix --apply` where a fix is available, then run your tests.
Official migration guide (excerpt, © The Flutter Authors, CC BY 3.0)
There might be situations where the ImageCache
is thrashing with the new logic where it wasn't previously,
specifically if you load images that are larger than your
cache.maxByteSize value.
This can be remedied by one of the following approaches:
- Increase the
ImageCache.maxByteSizevalue to accommodate larger images. - Adjust your image loading logic to guarantee that
the images fit nicely into the
ImageCache.maxByteSizevalue of your choosing. - Subclass
ImageCache, implement your desired logic, and create a new binding that serves up your subclass ofImageCache(see the [image_cache.dart][] source).
AI_PROVIDER (for example to openai-compatible with a local Ollama or LM Studio endpoint) to enable grounded explanations. Everything else on this page works without an AI provider.Listed in the official breaking-changes index (docs.flutter.dev/release/breaking-changes).
An official announcement or migration guide documents an intended behaviour or API change. A verified source change (git diff) shows code changed but does not by itself prove a public API is breaking. AI interpretations are labelled and never used to classify a change.
- Official migration guide
- ImageCache
- Issue 45643
- Stopped increasing the cache size to accommodate large images
- ImageCache source
- Source commit
- b3045439b7c0
- Source last updated
- Oct 21, 2026
- Last synchronized
- Oct 21, 2026
- Publication status
- published
Publication history
- Oct 21, 2026, 8:31 PM: new → published (ingestion) — Backed by an official breaking-change/migration guide.
AI_PROVIDER (for example to openai-compatible with a local Ollama or LM Studio endpoint) to enable grounded explanations. Everything else on this page works without an AI provider.