Repair a Flutter Pub Cache Error Without Clearing Every Cache

Read the failing path

Pub cache errors often name a package directory, archive, or checksum. Save that first path and the surrounding error before cleaning anything. A download timeout, permission problem, and corrupt archive need different fixes, even if each appears during flutter pub get.

Check the configured cache location and free space:

dart pub cache
df -h
flutter pub get -v

If the error identifies one package and describes a damaged cached artifact, dart pub cache repair is a targeted supported repair that revalidates cached packages. It may redownload package data, so run it with a working network connection. For a permission failure, inspect ownership of the named cache directory; do not solve it by running Flutter as root.

Keep project build caches separate

The pub package cache is not the same as .dart_tool, Flutter build output, Gradle caches, or Xcode DerivedData. Clearing all of them at once can make the next build take much longer and destroys evidence about which layer was broken.

After repairing the package cache, run flutter pub get again. If dependency resolution succeeds but compilation still fails, the cache was not the compile issue. Move to the first compiler or Gradle error rather than repeating cache cleanup.

For CI, cache the Pub directory using keys that reflect the OS and relevant lockfile. A cache miss should remain safe because the lockfile defines resolution. A cache hit should only improve speed; it must not be required for correctness. If the same cache fails on one runner but not another, compare permissions, architecture, and cache restoration behavior before adding broad cleanup steps to every job.

Distinguish a damaged archive from a failed download

A truncated download caused by a temporary network failure can leave a partial file that looks like cache corruption on the next run. Compare the first failure with subsequent failures: a checksum mismatch or archive extraction error that names the same package repeatedly is stronger evidence of a bad cached artifact than a single timeout. If the problem happens only behind a proxy, inspect the proxy response and certificate configuration rather than repeatedly repairing a cache that will be repopulated with the same invalid response.

Record the package name and the cache path mentioned by Pub. Check that the directory belongs to the current user and that the filesystem has enough free space. On shared runners, confirm that two jobs are not mutating the same cache directory concurrently. A cache should be treated as disposable acceleration data, not as a shared package installation location that multiple processes modify without coordination. If ownership is wrong, correct the runner image or cache mount rather than running the build as a privileged user.

Repair narrowly, then verify the dependency graph

Use dart pub cache repair when the evidence points to damaged cached package content. Expect it to validate and potentially download package data, so use it in an environment with known network access and capture the duration. If one package alone is broken and your Pub version supports a targeted cache removal workflow, prefer that over deleting unrelated SDK and build caches. Do not remove .dart_tool and Gradle state unless the failure points to those layers; they are not the Pub package archive store.

After repair, run the same dependency command that failed and compare the resulting lockfile. The expected result is that the existing resolution is restored without an unexplained dependency update. Then run the smallest failing compile or test. If package resolution succeeds but compilation fails on a generated file or platform plugin, stop treating the incident as a cache problem and investigate that next layer.

For CI, key cache entries on operating system, relevant lockfiles, and toolchain where appropriate. A cache miss must still produce a correct build from the lockfile, and a cache hit must not be the only reason the build passes. Consider caching downloads separately from mutable build output. This makes a cold-run test meaningful: periodically run without a restored cache to prove the project can be rebuilt from its declared inputs.

Distinguish a damaged archive from a failed download

A truncated download caused by a temporary network failure can leave a partial file that looks like cache corruption on the next run. Compare the first failure with subsequent failures: a checksum mismatch or archive extraction error that names the same package repeatedly is stronger evidence of a bad cached artifact than a single timeout. If the problem happens only behind a proxy, inspect the proxy response and certificate configuration rather than repeatedly repairing a cache that will be repopulated with the same invalid response.

Record the package name and the cache path mentioned by Pub. Check that the directory belongs to the current user and that the filesystem has enough free space. On shared runners, confirm that two jobs are not mutating the same cache directory concurrently. A cache should be treated as disposable acceleration data, not as a shared package installation location that multiple processes modify without coordination. If ownership is wrong, correct the runner image or cache mount rather than running the build as a privileged user.

Repair narrowly, then verify the dependency graph

Use dart pub cache repair when the evidence points to damaged cached package content. Expect it to validate and potentially download package data, so use it in an environment with known network access and capture the duration. If one package alone is broken and your Pub version supports a targeted cache removal workflow, prefer that over deleting unrelated SDK and build caches. Do not remove .dart_tool and Gradle state unless the failure points to those layers; they are not the Pub package archive store.

After repair, run the same dependency command that failed and compare the resulting lockfile. The expected result is that the existing resolution is restored without an unexplained dependency update. Then run the smallest failing compile or test. If package resolution succeeds but compilation fails on a generated file or platform plugin, stop treating the incident as a cache problem and investigate that next layer.

For CI, key cache entries on operating system, relevant lockfiles, and toolchain where appropriate. A cache miss must still produce a correct build from the lockfile, and a cache hit must not be the only reason the build passes. Consider caching downloads separately from mutable build output. This makes a cold-run test meaningful: periodically run without a restored cache to prove the project can be rebuilt from its declared inputs.