Introduction

The Flutter pub cache stores downloaded packages globally on your machine. Corruption can occur due to interrupted downloads, disk errors, IDE interference during package resolution, or switching between Flutter versions. When corruption happens, flutter pub get may succeed but the app fails to compile with missing file errors, or package code behaves unexpectedly. The flutter pub cache repair command validates and re-downloads corrupted packages.

Symptoms

  • Compilation errors referencing package files:
  • `
  • Error: Couldn't resolve the package 'http' in 'package:http/http.dart'.
  • `
  • Or runtime errors:
  • `
  • Error: Module not found: 'package:flutter/material.dart'
  • `
  • flutter pub get succeeds but flutter run fails
  • Inconsistent behavior across different developer machines
  • Error:
  • `
  • Because my_app depends on package_name which doesn't exist, version solving failed.
  • `

Common Causes

  • Interrupted flutter pub get or dart pub get during download
  • Disk full during package extraction
  • Anti-virus software quarantining package files
  • Switching Flutter SDK versions without cleaning cache
  • Manual deletion of cache files
  • File system corruption

Step-by-Step Fix

  1. 1.Run pub cache repair to validate all packages:
  2. 2.```bash
  3. 3.flutter pub cache repair
  4. 4.`
  5. 5.This checks every cached package and re-downloads corrupted ones. Output looks like:
  6. 6.`
  7. 7.Downloading http 1.2.1...
  8. 8.Downloading provider 6.1.2...
  9. 9.Got dependencies!
  10. 10.`
  11. 11.If repair fails, clean the entire cache and re-download:
  12. 12.```bash
  13. 13.flutter pub cache clean
  14. 14.flutter pub get
  15. 15.`
  16. 16.This removes all cached packages and re-downloads only what your project needs.
  17. 17.Check cache location to inspect manually:
  18. 18.```bash
  19. 19.# Show cache directory
  20. 20.flutter pub cache repair --dry-run

# Default locations: # macOS/Linux: $HOME/.pub-cache # Windows: %LOCALAPPDATA%\Pub\Cache flutter pub cache info ```

  1. 1.Remove a specific corrupted package:
  2. 2.```bash
  3. 3.# Find the package in cache
  4. 4.ls ~/.pub-cache/hosted/pub.dev/

# Remove specific version rm -rf ~/.pub-cache/hosted/pub.dev/http-1.2.0/

# Re-download flutter pub get ```

  1. 1.Use PUB_CACHE environment variable for a clean cache:
  2. 2.```bash
  3. 3.# Set a fresh cache directory
  4. 4.export PUB_CACHE=$HOME/.pub-cache-clean
  5. 5.flutter pub get
  6. 6.`
  7. 7.Fix permission issues on the cache directory:
  8. 8.```bash
  9. 9.# Fix ownership
  10. 10.sudo chown -R $USER ~/.pub-cache

# Fix permissions chmod -R u+rw ~/.pub-cache ```

Prevention

  • Do not interrupt flutter pub get while it is running
  • Keep adequate disk space (at least 2 GB free for pub cache)
  • Add anti-virus exclusions for the pub cache directory
  • Use flutter clean && flutter pub get when switching branches with different dependencies
  • Run flutter pub cache repair periodically as maintenance
  • Use flutter pub deps to verify all packages are properly resolved
  • Set up CI/CD pipelines with a clean pub cache for each build to catch cache-dependent issues
  • Document the pub cache location in your team onboarding guide so developers know where to look