vercel/next.js · error · Error

Could not prepare the upgrade guide.

Error message

Could not prepare the upgrade guide.

What it means

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.

Solutions

1. Reinstall/rebuild next so the bundled docs match the CLI (pnpm --filter=next build for source builds)
2. Verify the guide contains the placeholder: grep codemod-command node_modules/next/dist/docs/01-app/02-guides/upgrading/agentic-upgrade.md
3. If in a fork/patch, re-add the <codemod-command> placeholder to the guide
4. Clear node_modules and lockfile, then fresh install

Example fix

// verify in the bundled guide
// before (guide edited, placeholder removed)
Run the upgrade codemod.
// after
Run `<codemod-command>` to perform the upgrade.

const guide = await readFile(guidePath, 'utf8')
if (!guide.includes('<codemod-command>')) {
  console.error('Bundled guide missing <codemod-command> placeholder; reinstall next')
}

try {
  await spawnNextUpgrade(dir, options)
} catch (e) {
  if (e.message.includes('Could not prepare the upgrade guide')) {
    // verify bundled docs and reinstall/rebuild next
  }
}

When it happens

Trigger: 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.

Common situations: Custom or partial next install with missing docs; a fork where the guide was edited; interrupted install leaving truncated files.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• Could not prepare adoption documents for
• Unsupported upgrade document
• AI upgrades are not available for prerelease versions of…
• Could not check Next.js security advisories. Continuing…
• Could not determine the installed Next.js version.

AI-assisted analysis of vercel/next.js@34433fd12e (2026-09-20). Data as JSON: /api/errors/1ca640afc0aa6d95. Report an issue: GitHub.

Appendix: source

Thrown at packages/next/src/cli/next-upgrade.ts:251

      try {
        for (const router of ['01-app', '02-pages']) {
          await cp(
            join(bundledDocs, router, '02-guides/upgrading'),
            join(runDirectory, 'docs', router, '02-guides/upgrading'),
            { recursive: true }
          )
        }

        if (needsVersionMigration) {
          const codemodVersion = process.env.__NEXT_VERSION
          if (!codemodVersion) {
            throw new Error('Could not determine the @next/codemod version.')
          }
          const codemodCommand = `${getNpxCommand(baseDir)} @next/codemod@${codemodVersion} upgrade ${result.targetVersion} --yes --skip-adoption${options.verbose ? ' --verbose' : ''}`
          const guide = await readFile(guidePath, 'utf8')
          if (!guide.includes(CODEMOD_COMMAND_PLACEHOLDER)) {
            throw new Error('Could not prepare the upgrade guide.')
          }
          await writeFile(
            guidePath,
            guide.replace(CODEMOD_COMMAND_PLACEHOLDER, codemodCommand)
          )
        }
      } catch (error) {
        await rm(runDirectory, { recursive: true, force: true })
        throw error
      } finally {
        guidesSpinner?.stop()
      }

      const preparedFutureDefaults: Array<
        (typeof result.futureDefaults)[number] & {
          documents: string[]
        }
      > = []

View on GitHub (pinned to 34433fd12e)