nodejs/node · warning · Error

As of npm@5, the npm cache self-heals from corruption issues

Error message

As of npm@5, the npm cache self-heals from corruption issues by treating integrity mismatches as cache misses.
As a result, data extracted from the cache is guaranteed to be valid.
If you want to make sure everything is consistent, use `npm cache verify` instead.
Deleting the cache can only make npm go slower, and is not likely to correct any problems you may be encountering!

On the other hand, if you're debugging an issue with the installer, or race conditions that depend on the timing of writing to an empty cache, you can use `npm install --cache /tmp/empty-cache` to use a temporary cache instead of removing the actual one.

If you're sure you want to delete the entire cache, rerun this command with --force.

What it means

`npm cache clean` (with no arguments) is intentionally blocked unless --force is set. Since npm v5 the cache self-heals integrity mismatches by treating them as cache misses, so deleting it only slows things down. The message steers users to `npm cache verify` or a temporary cache instead.

Source

Thrown at deps/npm/lib/commands/cache.js:134

    switch (cmd) {
      case 'ls':
        return await this.npxLs(keys)
      case 'rm':
        return await this.npxRm(keys)
      case 'info':
        return await this.npxInfo(keys)
      default:
        throw this.usageError()
    }
  }

  // npm cache clean [spec]*
  async clean (args) {
    // this is a derived value
    const cachePath = this.npm.flatOptions.cache
    if (args.length === 0) {
      if (!this.npm.config.get('force')) {
        throw new Error(`As of npm@5, the npm cache self-heals from corruption issues by treating integrity mismatches as cache misses.
As a result, data extracted from the cache is guaranteed to be valid.
If you want to make sure everything is consistent, use \`npm cache verify\` instead.
Deleting the cache can only make npm go slower, and is not likely to correct any problems you may be encountering!

On the other hand, if you're debugging an issue with the installer, or race conditions that depend on the timing of writing to an empty cache, you can use \`npm install --cache /tmp/empty-cache\` to use a temporary cache instead of removing the actual one.

If you're sure you want to delete the entire cache, rerun this command with --force.`)
      }
      return fs.rm(cachePath, { recursive: true, force: true })
    }
    for (const key of args) {
      let entry
      try {
        entry = await cacache.get(cachePath, key)
      } catch {
        log.warn('cache', `Not Found: ${key}`)
        break
      }

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Run `npm cache verify` to validate and reclaim without deleting
2. Use a throwaway cache for the install: `npm install --cache /tmp/empty-cache`
3. If you truly need a full wipe, rerun `npm cache clean --force`

Example fix

# before
npm cache clean

# after
npm cache verify

// Prefer verify; only allow clean with explicit force
function safeCacheCommand(userArgs) {
  const clean = userArgs[0] === 'clean' && userArgs.length === 1 && !userArgs.includes('--force')
  if (clean) return ['cache', 'verify']
  return ['cache', ...userArgs]
}

function needsForceForClean(args) {
  return args[0] === 'clean' && args.length === 1 && !args.includes('--force')
}

When it happens

Trigger: Running `npm cache clean` with no package args and without --force. The guard is bypassed only when args.length === 0 AND force is falsy, so `npm cache clean <key>` or `npm cache clean --force` do not hit it.

Common situations: Developers who learned `npm cache clean` from npm v4 tutorials trying to fix install corruption; CI freeing disk space; debugging flaky installs.

Related errors

• Cannot use --no-workspaces and --workspace at the same time
• Please provide only one of ${flagList}
• Unknown positional argument: ${extra}
• ${argv[2]} not recognized
• `${baseKey}` is not a valid npm option

AI-assisted analysis of nodejs/node@1b2de5e052 (2026-08-13). Data as JSON: /api/errors/fb0d1c0f1874b475. Report an issue: GitHub.