{"record":{"id":"1ca640afc0aa6d95","repo":"vercel/next.js","slug":"could-not-prepare-the-upgrade-guide","errorCode":null,"errorMessage":"Could not prepare the upgrade guide.","messagePattern":"Could not prepare the upgrade guide\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/next/src/cli/next-upgrade.ts","lineNumber":251,"sourceCode":"\n      try {\n        for (const router of ['01-app', '02-pages']) {\n          await cp(\n            join(bundledDocs, router, '02-guides/upgrading'),\n            join(runDirectory, 'docs', router, '02-guides/upgrading'),\n            { recursive: true }\n          )\n        }\n\n        if (needsVersionMigration) {\n          const codemodVersion = process.env.__NEXT_VERSION\n          if (!codemodVersion) {\n            throw new Error('Could not determine the @next/codemod version.')\n          }\n          const codemodCommand = `${getNpxCommand(baseDir)} @next/codemod@${codemodVersion} upgrade ${result.targetVersion} --yes --skip-adoption${options.verbose ? ' --verbose' : ''}`\n          const guide = await readFile(guidePath, 'utf8')\n          if (!guide.includes(CODEMOD_COMMAND_PLACEHOLDER)) {\n            throw new Error('Could not prepare the upgrade guide.')\n          }\n          await writeFile(\n            guidePath,\n            guide.replace(CODEMOD_COMMAND_PLACEHOLDER, codemodCommand)\n          )\n        }\n      } catch (error) {\n        await rm(runDirectory, { recursive: true, force: true })\n        throw error\n      } finally {\n        guidesSpinner?.stop()\n      }\n\n      const preparedFutureDefaults: Array<\n        (typeof result.futureDefaults)[number] & {\n          documents: string[]\n        }\n      > = []","sourceCodeStart":233,"sourceCodeEnd":269,"githubUrl":"https://github.com/vercel/next.js/blob/34433fd12ee8074ea3f47af9f36255c7390d0301/packages/next/src/cli/next-upgrade.ts#L233-L269","documentation":"The bundled agentic-upgrade guide template must contain the literal placeholder <codemod-command>, which the CLI replaces with the concrete npx codemod command. If the placeholder is absent, the guide shipped with this build is inconsistent with the code and the CLI refuses to hand an unfilled template to the agent.","triggerScenarios":"The bundled docs/01-app/02-guides/upgrading/agentic-upgrade.md in this build lacks '<codemod-command>' — docs and code out of sync in the distribution, or the copied guide file is truncated/corrupted.","commonSituations":"Custom or partial next install with missing docs; a fork where the guide was edited; interrupted install leaving truncated files.","solutions":["Reinstall/rebuild next so the bundled docs match the CLI (pnpm --filter=next build for source builds)","Verify the guide contains the placeholder: grep codemod-command node_modules/next/dist/docs/01-app/02-guides/upgrading/agentic-upgrade.md","If in a fork/patch, re-add the <codemod-command> placeholder to the guide","Clear node_modules and lockfile, then fresh install"],"exampleFix":"// verify in the bundled guide\n// before (guide edited, placeholder removed)\nRun the upgrade codemod.\n// after\nRun `<codemod-command>` to perform the upgrade.","handlingStrategy":"try-catch","validationCode":"const guide = await readFile(guidePath, 'utf8')\nif (!guide.includes('<codemod-command>')) {\n  console.error('Bundled guide missing <codemod-command> placeholder; reinstall next')\n}","typeGuard":null,"tryCatchPattern":"try {\n  await spawnNextUpgrade(dir, options)\n} catch (e) {\n  if (e.message.includes('Could not prepare the upgrade guide')) {\n    // verify bundled docs and reinstall/rebuild next\n  }\n}","preventionTips":["Never edit placeholder tokens in bundled next docs","Keep docs and CLI changes in the same PR so the guide always contains <codemod-command>","Verify installs with a checksum or a clean reinstall when files look truncated"],"tags":["nextjs","upgrade","docs","internal-invariant"],"backgroundTag":"internal-invariant-violation","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"}