{"record":{"id":"c23ef0aec2518cf3","repo":"vercel/next.js","slug":"could-not-prepare-an-upgrade-retry-this-command-will-remain","errorCode":null,"errorMessage":"Could not prepare an upgrade retry. This command will remain blocked.","messagePattern":"Could not prepare an upgrade retry\\. This command will remain blocked\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"packages/next/src/lib/upgrade/nudge.ts","lineNumber":115,"sourceCode":"  }\n\n  await writeRetry(receipt, Date.now())\n  return false\n}\n\nasync function showNudge(\n  options: SecurityNudgeOptions,\n  version: string,\n  kind: NudgeKind,\n  prompt: string,\n  warning: string,\n  errorName: string\n): Promise<void> {\n  let retryAllowed = false\n  try {\n    retryAllowed = await allowNudgeRetry(options, version, kind)\n  } catch {\n    Log.warn(\n      'Could not prepare an upgrade retry. This command will remain blocked.'\n    )\n  }\n\n  if (retryAllowed) {\n    Log.warn(warning)\n    return\n  }\n\n  const error = new Error(prompt)\n  error.name = errorName\n  Object.assign(error, { exitCode: 1 })\n  throw error\n}\n\nasync function getLatestUpgrade(\n  installedVersion: string = process.env.__NEXT_VERSION || 'unknown'\n): Promise<{ installedVersion: string; latestVersion: string } | null> {","sourceCodeStart":97,"sourceCodeEnd":133,"githubUrl":"https://github.com/vercel/next.js/blob/34433fd12ee8074ea3f47af9f36255c7390d0301/packages/next/src/lib/upgrade/nudge.ts#L97-L133","documentation":"Before showing an upgrade nudge (security, latest, or future), showNudge calls allowNudgeRetry to decide whether the user may be re-prompted. If allowNudgeRetry throws (e.g. its persistence/IO fails), the nudge logic cannot determine retry eligibility, logs this warning, and treats the nudge as still blocked rather than crashing the command.","triggerScenarios":"Any `next dev`/`next build`/CLI invocation that triggers nudgeForSecurity/nudgeForLatest/nudgeForFuture while allowNudgeRetry throws — typically a failing state-file read/write or unexpected data in the nudge state store.","commonSituations":"Read-only or full disk where nudge state cannot be persisted, corrupted nudge state file, or permission errors in the config/cache directory.","solutions":["Fix permissions/disk space in the directory where Next.js stores its state (HOME config/cache dirs).","Delete the nudge/upgrade state file so it is recreated fresh.","Re-run the command; if it persists, run with NEXT_TELEMETRY_DISABLED and debug logging to locate the failing IO."],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"// Ensure the state directory is writable before running commands that nudge\nimport { accessSync, constants } from 'fs'\nfunction stateDirWritable(dir: string): boolean {\n  try {\n    accessSync(dir, constants.W_OK)\n    return true\n  } catch {\n    return false\n  }\n}","typeGuard":null,"tryCatchPattern":"try {\n  await runCliCommand()\n} catch (e) {\n  if (String(e).includes('Could not prepare an upgrade retry')) {\n    // fix HOME/config dir permissions, delete nudge state, re-run\n  } else throw e\n}","preventionTips":["Keep the user config/cache directory writable (check HOME and disk quota).","Delete stale nudge state files if upgrade prompts behave oddly.","In CI, set non-interactive env so nudges don't attempt interactive retries."],"tags":["upgrade","cli","state-persistence","nextjs"],"backgroundTag":"file-write-failed","analyzedSha":"34433fd12ee8074ea3f47af9f36255c7390d0301","analyzedAt":"2026-09-20T18:20:20.576Z","contentChangedAt":"2026-09-20T18:20:20.576Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}