{"record":{"id":"fb0d1c0f1874b475","repo":"nodejs/node","slug":"as-of-npm-5-the-npm-cache-self-heals-from-corrupt","errorCode":null,"errorMessage":"As of npm@5, the npm cache self-heals from corruption issues by treating integrity mismatches as cache misses.\nAs a result, data extracted from the cache is guaranteed to be valid.\nIf you want to make sure everything is consistent, use `npm cache verify` instead.\nDeleting the cache can only make npm go slower, and is not likely to correct any problems you may be encountering!\n\nOn 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.\n\nIf you're sure you want to delete the entire cache, rerun this command with --force.","messagePattern":"As of npm@5, the npm cache self-heals from corruption issues by treating integrity mismatches as cache misses\\.\nAs a result, data extracted from the cache is guaranteed to be valid\\.\nIf you want to make sure everything is consistent, use `npm cache verify` instead\\.\nDeleting the cache can only make npm go slower, and is not likely to correct any problems you may be encountering!\n\nOn 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\\.\n\nIf you're sure you want to delete the entire cache, rerun this command with --force\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"warning","filePath":"deps/npm/lib/commands/cache.js","lineNumber":134,"sourceCode":"    switch (cmd) {\n      case 'ls':\n        return await this.npxLs(keys)\n      case 'rm':\n        return await this.npxRm(keys)\n      case 'info':\n        return await this.npxInfo(keys)\n      default:\n        throw this.usageError()\n    }\n  }\n\n  // npm cache clean [spec]*\n  async clean (args) {\n    // this is a derived value\n    const cachePath = this.npm.flatOptions.cache\n    if (args.length === 0) {\n      if (!this.npm.config.get('force')) {\n        throw new Error(`As of npm@5, the npm cache self-heals from corruption issues by treating integrity mismatches as cache misses.\nAs a result, data extracted from the cache is guaranteed to be valid.\nIf you want to make sure everything is consistent, use \\`npm cache verify\\` instead.\nDeleting the cache can only make npm go slower, and is not likely to correct any problems you may be encountering!\n\nOn 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.\n\nIf you're sure you want to delete the entire cache, rerun this command with --force.`)\n      }\n      return fs.rm(cachePath, { recursive: true, force: true })\n    }\n    for (const key of args) {\n      let entry\n      try {\n        entry = await cacache.get(cachePath, key)\n      } catch {\n        log.warn('cache', `Not Found: ${key}`)\n        break\n      }","sourceCodeStart":116,"sourceCodeEnd":152,"githubUrl":"https://github.com/nodejs/node/blob/1b2de5e052fc0fb95fd7fb6846dcec4ade598e9e/deps/npm/lib/commands/cache.js#L116-L152","documentation":"`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.","triggerScenarios":"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.","commonSituations":"Developers who learned `npm cache clean` from npm v4 tutorials trying to fix install corruption; CI freeing disk space; debugging flaky installs.","solutions":["Run `npm cache verify` to validate and reclaim without deleting","Use a throwaway cache for the install: `npm install --cache /tmp/empty-cache`","If you truly need a full wipe, rerun `npm cache clean --force`"],"exampleFix":"# before\nnpm cache clean\n\n# after\nnpm cache verify","handlingStrategy":"validation","validationCode":"// Prefer verify; only allow clean with explicit force\nfunction safeCacheCommand(userArgs) {\n  const clean = userArgs[0] === 'clean' && userArgs.length === 1 && !userArgs.includes('--force')\n  if (clean) return ['cache', 'verify']\n  return ['cache', ...userArgs]\n}","typeGuard":"function needsForceForClean(args) {\n  return args[0] === 'clean' && args.length === 1 && !args.includes('--force')\n}","tryCatchPattern":null,"preventionTips":["Default to `npm cache verify` instead of `npm cache clean`","Use a temporary cache (--cache /tmp/empty-cache) when reproducing installer bugs","Only pass --force when you accept the performance cost of a full re-download"],"tags":["cache","cli","deprecation","guardrail"],"backgroundTag":null,"analyzedSha":"1b2de5e052fc0fb95fd7fb6846dcec4ade598e9e","analyzedAt":"2026-08-13T00:53:24.642Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}