Diagnosing Webpack 5 Filesystem Cache Issues: Stale Builds, Missed Hits, and Corruption

Recognizable Condition

When using Webpack 5 with cache.type: 'filesystem', you may observe one of the following symptoms:

• Stale output: bundles contain old code after you edit a source file.
• Cold cache every run: each build takes as long as a no‑cache build, even though the cache directory exists.
• Intermittent "Module not found" errors after switching branches or updating dependencies.

Cause/Diagnostic Table

Symptom	Likely Cause	What to Inspect
Stale output	Cache not invalidated or missing buildDependencies	Check that config files, loaders, and plugins are listed in cache.buildDependencies
Cold cache every run	Cache disabled, wrong cacheDirectory, or snapshots turned off	Verify cache.type, writable cacheDirectory, and that snapshot options are not overridden to false
Module not found / random resolution failures	Corrupted cache files or version mismatch in package-lock.json	Look for broken JSON in the cache directory, compare webpack and node versions across runs

Ordered Checks

1. Confirm cache configuration

   Run the build with JSON stats to see the effective cache settings:

   # In the project root, you need read access to node_modules and write access to the cache dir
   webpack --profile --json > stats.json
   

   Open stats.json and locate the output → cache section. Ensure:

   • type equals "filesystem"
   • cacheDirectory points to a directory that exists and is writable by the user running Webpack.
2. Validate buildDependencies

   In the same stats output, find cache → buildDependencies. It should be an array of absolute paths. Typical entries include:

   • Your Webpack config file (webpack.config.js)
   • Loader and plugin modules (e.g., path/to/node_modules/babel-loader/lib/index.js)
   • Any custom files you import via require.context or similar.

   If a loader you added recently is missing, the cache will not invalidate when that loader changes.

3. Inspect the cache directory

   Locate the directory from cacheDirectory (default .webpack_cache). Inside you should see:

   • lastHash file – a hash representing the current build.
   • Timestamped sub‑folders for each module/chunk.

   Run a quick check:

   ls -la .webpack_cache
   # You should see lastHash and a number of folders, not just an empty directory.
   

   If the directory is empty or only contains lastHash with an old timestamp, the cache is not being populated.

4. Isolate cache vs. compiler logic

   Run a build with caching disabled to see if the problem persists:

   webpack --no-cache
   

   If the build succeeds and produces correct output, the issue lies in the cache layer. If the problem remains, look at loader/plugin configuration or file watchers.

5. Check snapshot settings

   Webpack uses snapshots to track file changes. Ensure they are not overridden:

   module.exports = {
     // …
     snapshot: {
       managedPaths: [path.resolve(__dirname, 'node_modules')],
       immutablePaths: [],
       // do not set buildDependencies: false unless you know what you are doing
     }
   };
   

   Verify that managedPaths includes your node_modules folder; otherwise changes inside dependencies will not invalidate the cache.

Fixes Tied to Findings

Stale Output

1. Delete the cache directory to force a fresh start:

rm -rf .webpack_cache

Then add missing dependencies to cache.buildDependencies. Example snippet:

module.exports = {
  cache {
    type: 'filesystem',
    cacheDirectory: path.resolve(__dirname, '.webpack_cache'),
    buildDependencies: [
      configFile, // e.g., __dirname + '/webpack.config.js'
      path.resolve(__dirname, 'node_modules/babel-loader/lib/index.js'),
      // add any custom config files you load
    ],
  },
};

After saving, run two consecutive builds. The second should be noticeably faster and contain the updated code.

Cold Cache Every Run

1. Ensure cacheDirectory is not inside a temporary folder that gets cleared between CI steps (e.g., /tmp on some agents). Use a path relative to the project or a persistent volume.
2. Confirm the directory is writable:

# As the user that runs Webpack
touch .webpack_cache/testwrite && rm .webpack_cache/testwrite

3. If you see permission errors in the terminal, adjust folder ownership or run Webpack with a user that has write access.

Corrupted Cache

1. Remove the cache directory (as above).
2. Check disk space: a full disk can cause truncated cache files.

df -h .

3. Verify that the webpack and node versions used to create the cache match those used for the new build. A version mismatch can produce invalid hash calculations.
4. After clearing, run a build and inspect the lastHash file; it should change after each successful build.

Escalation Criteria

Escalate to the Webpack issue tracker when:

• After deleting the cache directory and verifying cache.buildDependencies is correct, a clean build still produces stale or incorrect output.
• Identical source, dependencies, and Webpack configuration yield different cache hashes on the same machine across runs.
• A specific loader or plugin appears to bypass snapshot invalidation (e.g., changes to a loader do not trigger a rebuild).

When opening an issue, include:

• The output of webpack --json (or stats.json) showing the cache section.
• A minimal reproduction repository or a gist with the relevant webpack.config.js, package.json, and the steps to reproduce.
• Notes on the host OS, Node.js version, and Webpack version (webpack -v).