{"record":{"id":"e671b9df0dc18c75","repo":"vercel/next.js","slug":"could-not-prepare-upgrade-document-document","errorCode":null,"errorMessage":"Could not prepare upgrade document ${document}.","messagePattern":"Could not prepare upgrade document (.+?)\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"packages/next/src/cli/next-upgrade.ts","lineNumber":290,"sourceCode":"        const contextSpinner = createSpinner('Preparing upgrade context')\n\n        try {\n          for (const futureDefault of result.futureDefaults) {\n            const documents: string[] = []\n\n            for (const document of futureDefault.adoptionDoc) {\n              try {\n                documents.push(\n                  await prepareUpgradeDocument({\n                    directory: baseDir,\n                    runDirectory,\n                    bundledDocs,\n                    nextVersion: result.targetVersion,\n                    document,\n                  })\n                )\n              } catch {\n                Log.warn(`Could not prepare upgrade document ${document}.`)\n              }\n            }\n\n            if (documents.length === 0) {\n              throw new Error(\n                `Could not prepare adoption documents for ${futureDefault.name}.`\n              )\n            }\n\n            preparedFutureDefaults.push({\n              ...futureDefault,\n              documents,\n            })\n          }\n        } finally {\n          contextSpinner?.stop()\n        }\n      }","sourceCodeStart":272,"sourceCodeEnd":308,"githubUrl":"https://github.com/vercel/next.js/blob/34433fd12ee8074ea3f47af9f36255c7390d0301/packages/next/src/cli/next-upgrade.ts#L272-L308","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Before running the upgrade, confirm network egress and clean install\n// npx next doctor  (or) curl -fsS https://nextjs.org -o /dev/null && echo ok","typeGuard":null,"tryCatchPattern":"try {\n  await nextUpgrade({ /* target */ })\n} catch (e) {\n  // Upgrade document warnings are non-fatal; verify the actual version bump:\n  const v = require('next/package.json').version\n  if (v !== targetVersion) throw e\n}","preventionTips":["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)."],"tags":["upgrade","cli","migration","nextjs"],"backgroundTag":"network-request-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"}