vercel/next.js · error · Error

Could not prepare adoption documents for

Error message

Could not prepare adoption documents for ${futureDefault.name}.

What it means

For each future default, the CLI attempts to prepare every adoptionDoc; individual failures are downgraded to warnings, but if every document for a default fails to prepare, there is no adoption context for the agent and the CLI throws naming the future default. Root causes surface earlier as 'Could not prepare upgrade document ...' warnings (bad doc paths, skills CLI download failures, network errors).

Solutions

1. Check earlier warnings 'Could not prepare upgrade document <doc>' for the root cause
2. Restore network access / proxy allowlist for registry.npmjs.org and github.com so npx skills can fetch
3. Fix the adoptionDoc paths in future-defaults.ts if they are invalid
4. Retry the upgrade once connectivity is restored

Example fix

// before: offline run
next upgrade --ai=future   # skills fetch fails for every doc
// after: ensure network or pre-cache
npm i -g skills@1.5.26 && next upgrade --ai=future

// pre-flight: ensure network reachability for the skills fetch
const ok = await fetch('https://registry.npmjs.org/skills/latest').then(r => r.ok).catch(() => false)
if (!ok) console.error('Network required to fetch upgrade skills')

try {
  await spawnNextUpgrade(dir, { ai: 'future' })
} catch (e) {
  if (e.message.startsWith('Could not prepare adoption documents')) {
    // inspect earlier 'Could not prepare upgrade document' warnings for root cause
  }
}

When it happens

Trigger: All adoptionDoc entries for one future default fail: paths unrecognized (error 0), skills CLI npx download fails offline, GitHub fetch of the skill fails, or docs copy fails.

Common situations: Offline/CI environments where npx cannot fetch skills@<version>; corporate proxies blocking github.com; a future default whose adoptionDoc entries are all misconfigured.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• Could not check Next.js security advisories. Continuing…
• Could not determine the latest stable Next.js version.
• Could not prepare the upgrade guide.
• AI upgrades are not available for prerelease versions of…
• Could not check for security updates. Please try again.

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

Appendix: source

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

            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()
        }
      }

      const references = result.references
        .map((reference) => `- ${reference}`)
        .join('\n')
      const reason =

View on GitHub (pinned to 34433fd12e)