What causes "Could not prepare upgrade document ${document}." in vercel/next.js?

Re-run `next upgrade` with verbose output/network access ensured to see the underlying cause.

Could not prepare upgrade document

Error message

Could not prepare upgrade document ${document}.

What it means

During `next upgrade`, when targeting a future default (e.g. cacheComponents adoption), Next.js tries to prepare upgrade/adoption documents (fetching bundled docs and building a document for the user's project). If any step throws, the error is swallowed and this warning is logged instead of aborting the upgrade. It is non-fatal for that document, but if ALL documents fail, a subsequent error is thrown.

Solutions

Re-run `next upgrade` with verbose output/network access ensured to see the underlying cause.
Check network/proxy settings if docs are fetched remotely; retry after connectivity is restored.
Upgrade manually: install the target Next.js version and follow the migration guide for the future flag in the official docs.

Defensive patterns

Strategy: retry

Validate before calling

// Before running the upgrade, confirm network egress and clean install
// npx next doctor  (or) curl -fsS https://nextjs.org -o /dev/null && echo ok

Try / catch

try {
  await nextUpgrade({ /* target */ })
} catch (e) {
  // Upgrade document warnings are non-fatal; verify the actual version bump:
  const v = require('next/package.json').version
  if (v !== targetVersion) throw e
}

Prevention

Run upgrades with unrestricted network access (disable VPN/proxy blocks).
Commit or stash changes before upgrading so document preparation has a clean tree.
After any upgrade-document warning, cross-check the official migration guide manually.
Keep Next.js and its bundled docs versions aligned (reinstall node_modules after upgrading).

When it happens

Trigger: Running `next upgrade` (or the spawnNextUpgrade flow) with a future flag target where preparing one of the adoption documents throws — e.g. network failure fetching docs, unexpected project layout, or an error rendering the upgrade document from bundledDocs.

Common situations: Upgrading behind a proxy/firewall that blocks doc fetching, upgrading a project with unusual structure that breaks document preparation, or a broken/corrupted Next.js installation missing bundled docs.

Related errors

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

Appendix: source

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

        const contextSpinner = createSpinner('Preparing upgrade context')

        try {
          for (const futureDefault of result.futureDefaults) {
            const documents: string[] = []

            for (const document of futureDefault.adoptionDoc) {
              try {
                documents.push(
                  await prepareUpgradeDocument({
                    directory: baseDir,
                    runDirectory,
                    bundledDocs,
                    nextVersion: result.targetVersion,
                    document,
                  })
                )
              } catch {
                Log.warn(`Could not prepare upgrade document ${document}.`)
              }
            }

            if (documents.length === 0) {
              throw new Error(
                `Could not prepare adoption documents for ${futureDefault.name}.`
              )
            }

            preparedFutureDefaults.push({
              ...futureDefault,
              documents,
            })
          }
        } finally {
          contextSpinner?.stop()
        }
      }

View on GitHub (pinned to 34433fd12e)