{"record":{"id":"f6383d1e3f1dd72d","repo":"vercel/next.js","slug":"could-not-prepare-adoption-documents-for-futuredefault-name","errorCode":null,"errorMessage":"Could not prepare adoption documents for ${futureDefault.name}.","messagePattern":"Could not prepare adoption documents for (.+?)\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/next/src/cli/next-upgrade.ts","lineNumber":295,"sourceCode":"\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      }\n\n      const references = result.references\n        .map((reference) => `- ${reference}`)\n        .join('\\n')\n      const reason =","sourceCodeStart":277,"sourceCodeEnd":313,"githubUrl":"https://github.com/vercel/next.js/blob/34433fd12ee8074ea3f47af9f36255c7390d0301/packages/next/src/cli/next-upgrade.ts#L277-L313","documentation":"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).","triggerScenarios":"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.","commonSituations":"Offline/CI environments where npx cannot fetch skills@<version>; corporate proxies blocking github.com; a future default whose adoptionDoc entries are all misconfigured.","solutions":["Check earlier warnings 'Could not prepare upgrade document <doc>' for the root cause","Restore network access / proxy allowlist for registry.npmjs.org and github.com so npx skills can fetch","Fix the adoptionDoc paths in future-defaults.ts if they are invalid","Retry the upgrade once connectivity is restored"],"exampleFix":"// before: offline run\nnext upgrade --ai=future   # skills fetch fails for every doc\n// after: ensure network or pre-cache\nnpm i -g skills@1.5.26 && next upgrade --ai=future","handlingStrategy":"try-catch","validationCode":"// pre-flight: ensure network reachability for the skills fetch\nconst ok = await fetch('https://registry.npmjs.org/skills/latest').then(r => r.ok).catch(() => false)\nif (!ok) console.error('Network required to fetch upgrade skills')","typeGuard":null,"tryCatchPattern":"try {\n  await spawnNextUpgrade(dir, { ai: 'future' })\n} catch (e) {\n  if (e.message.startsWith('Could not prepare adoption documents')) {\n    // inspect earlier 'Could not prepare upgrade document' warnings for root cause\n  }\n}","preventionTips":["Ensure registry.npmjs.org and github.com are reachable (CI proxies/allowlists)","Pre-install or cache the skills CLI version used by the upgrade","Fix the root-cause warnings first; this error is aggregate"],"tags":["nextjs","upgrade","network","docs"],"backgroundTag":"file-read-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"}