{"record":{"id":"559e5a57bdad5a87","repo":"vercel/next.js","slug":"unsupported-upgrade-document-input-document","errorCode":null,"errorMessage":"Unsupported upgrade document ${input.document}.","messagePattern":"Unsupported upgrade document (.+?)\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/next/src/cli/next-upgrade.ts","lineNumber":48,"sourceCode":"  bundledDocs: string\n  nextVersion: string\n  document: UpgradeDocument\n}\n\nasync function prepareUpgradeDocument(\n  input: PrepareUpgradeDocumentInput\n): Promise<string> {\n  if (input.document.startsWith('docs/')) {\n    const path = input.document.slice('docs/'.length)\n    const destination = join(input.runDirectory, input.document)\n    await mkdir(dirname(destination), { recursive: true })\n    await cp(join(input.bundledDocs, path), destination)\n    return destination\n  }\n\n  const match = /^skills\\/(.+)\\/SKILL\\.md$/.exec(input.document)\n  if (!match) {\n    throw new Error(`Unsupported upgrade document ${input.document}.`)\n  }\n\n  return prepareUpgradeSkill(input, match[1])\n}\n\nasync function prepareUpgradeSkill(\n  input: PrepareUpgradeDocumentInput,\n  skill: string\n): Promise<string> {\n  const spawnCommand =\n    require('next/dist/compiled/cross-spawn') as typeof import('next/dist/compiled/cross-spawn')\n  const [command, ...runnerArgs] = getNpxCommand(input.directory).split(' ')\n  const source =\n    `https://github.com/vercel/next.js/tree/v${input.nextVersion}/skills/` +\n    skill\n  const args = [...runnerArgs, `skills@${SKILLS_CLI_VERSION}`, 'use', source]\n  const skillDirectory = join(input.runDirectory, 'skills', skill)\n  const instructionsPath = join(skillDirectory, 'PROMPT.md')","sourceCodeStart":30,"sourceCodeEnd":66,"githubUrl":"https://github.com/vercel/next.js/blob/34433fd12ee8074ea3f47af9f36255c7390d0301/packages/next/src/cli/next-upgrade.ts#L30-L66","documentation":"prepareUpgradeDocument copies an adoption document into the agent run directory. It supports two shapes: paths under 'docs/' copied from bundled docs, and 'skills/<name>/SKILL.md' paths fetched via the skills CLI. Any other document string has no supported resolution strategy, so it throws. This is an internal invariant over the future-defaults adoptionDoc data.","triggerScenarios":"future-defaults.ts lists an adoptionDoc entry that is neither 'docs/...' nor matches /^skills\\/(.+)\\/SKILL\\.md$/; a typo, renamed skill, or new document kind added without extending prepareUpgradeDocument.","commonSituations":"A Next.js contributor adds a new future default with a mistyped adoptionDoc path (e.g. 'skill/x/SKILL.md' or 'skills/x/skill.md'), or a bundled docs file is renamed so both branches fail.","solutions":["Fix the adoptionDoc path in packages/next/src/lib/upgrade/future-defaults.ts to start with 'docs/' or match 'skills/<name>/SKILL.md'","If a new document kind is needed, extend prepareUpgradeDocument with a matching branch","Check the warning 'Could not prepare upgrade document <doc>' in output to identify the offending document","If all documents for a default fail, the run fails with 'Could not prepare adoption documents'; fix the first warning"],"exampleFix":"// before (future-defaults.ts)\nadoptionDoc: ['skills/cache-components/skill.md']\n// after\nadoptionDoc: ['skills/cache-components/SKILL.md']","handlingStrategy":"validation","validationCode":"function isSupportedDocument(doc) {\n  return doc.startsWith('docs/') || /^skills\\/.+\\/SKILL\\.md$/.test(doc)\n}\nif (!adoptionDoc.every(isSupportedDocument)) {\n  throw new Error('bad adoptionDoc entry: ' + doc)\n}","typeGuard":"function isSupportedDocument(doc: string): boolean {\n  return doc.startsWith('docs/') || /^skills\\/.+\\/SKILL\\.md$/.test(doc)\n}","tryCatchPattern":null,"preventionTips":["Validate adoptionDoc entries against docs/ or skills/<name>/SKILL.md when adding future defaults","Add a unit test iterating futureDefaults and asserting every document passes isSupportedDocument","Keep SKILL.md filename casing exact"],"tags":["nextjs","upgrade","internal-invariant"],"backgroundTag":"unsupported-operation","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"}