{"record":{"id":"2dfde21351f332f0","repo":"vercel/next.js","slug":"could-not-find-documentation-for-next-js-tag-t","errorCode":null,"errorMessage":"Could not find documentation for Next.js ${tag}. This version may not exist on GitHub yet.","messagePattern":"Could not find documentation for Next\\.js (.+?)\\. This version may not exist on GitHub yet\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/next-codemod/lib/agents-md.ts","lineNumber":217,"sourceCode":"      await execa(\n        'git',\n        [\n          'clone',\n          '--depth',\n          '1',\n          '--filter=blob:none',\n          '--sparse',\n          '--branch',\n          tag,\n          'https://github.com/vercel/next.js.git',\n          '.',\n        ],\n        { cwd: tempDir }\n      )\n    } catch (error) {\n      const message = error instanceof Error ? error.message : String(error)\n      if (message.includes('not found') || message.includes('did not match')) {\n        throw new Error(\n          `Could not find documentation for Next.js ${tag}. This version may not exist on GitHub yet.`\n        )\n      }\n      throw error\n    }\n\n    await execa('git', ['sparse-checkout', 'set', 'docs'], { cwd: tempDir })\n\n    const sourceDocsDir = path.join(tempDir, 'docs')\n    if (!fs.existsSync(sourceDocsDir)) {\n      throw new Error('docs folder not found in cloned repository')\n    }\n\n    if (fs.existsSync(destDir)) {\n      fs.rmSync(destDir, { recursive: true })\n    }\n    fs.mkdirSync(destDir, { recursive: true })\n    fs.cpSync(sourceDocsDir, destDir, { recursive: true })","sourceCodeStart":199,"sourceCodeEnd":235,"githubUrl":"https://github.com/vercel/next.js/blob/0ae8c72462952df163f1b1e0726641bc5b40dc93/packages/next-codemod/lib/agents-md.ts#L199-L235","documentation":"`next-codemod`'s `agents-md` command clones the Next.js docs from GitHub at the tag matching your installed version (`v<major.minor.patch>`). If `git clone --branch <tag>` fails with 'not found' or 'did not match', this error is thrown. It means the GitHub repo has no ref for that exact tag — common for very new local/alpha builds whose tag hasn't been pushed, or for version strings that don't correspond to a published tag (e.g. `0.0.0`, a local-only version, or a monorepo-derived hash).","triggerScenarios":"Running `npx @next/codemod agents-md` when the detected `next` version has no matching `v<version>` tag on vercel/next.js — e.g. a locally linked `0.0.0`, an unpublished canary hash, or a brand-new release whose tag isn't pushed yet.","commonSituations":"Local development with `next` linked (version `0.0.0`); pre-release versions where the GitHub tag lags npm; monorepo workspace resolving a non-published version; using a fork whose tags differ.","solutions":["Pass an explicit version override if the codemod supports it (e.g. `--version 15.1.0`) so it targets a tag that exists.","Use the bundled docs path (Next 16.2+) which reads docs from `node_modules/next/dist/docs` and skips the GitHub clone entirely.","Confirm the tag exists: `git ls-remote --tags https://github.com/vercel/next.js.git | grep v<your-version>`.","If on a local/linked build, install the published version matching your intent before running the codemod."],"exampleFix":"# before — version has no tag\nnpx @next/codemod agents-md\n\n# after — pin a real published version, or use bundled docs\nnpx @next/codemod agents-md --version 15.1.6\ngit ls-remote --tags https://github.com/vercel/next.js.git | grep v15.1.6","handlingStrategy":"validation","validationCode":"// Before running agents-md, confirm the version tag exists on GitHub.\nimport { execSync } from 'node:child_process'\nconst ver = require('next/package.json').version\nconst tag = `v${ver}`\nconst exists = execSync(`git ls-remote --tags https://github.com/vercel/next.js.git ${tag}`).toString().trim()\nif (!exists) throw new Error(`Tag ${tag} not found on GitHub; pin --version`)","typeGuard":"function isPublishedTag(v: string): boolean {\n  return /^\\d+\\.\\d+\\.\\d+/.test(v) && v !== '0.0.0'\n}","tryCatchPattern":"try {\n  await pullDocs({ cwd })\n} catch (e) {\n  if (/Could not find documentation/.test(e.message)) {\n    console.error('Pin a published version via --version, or use bundled docs (Next 16.2+).')\n  }\n  throw e\n}","preventionTips":["Use the bundled docs path on Next 16.2+ to skip the clone.","Pass an explicit --version matching a real GitHub tag.","Avoid running agents-md against locally-linked 0.0.0 builds."],"tags":["next-codemod","agents-md","git","github","version-mismatch","documentation"],"analyzedSha":"0ae8c72462952df163f1b1e0726641bc5b40dc93","analyzedAt":"2026-08-06T19:44:29.143Z","schemaVersion":2},"datasetVersion":"2026-08-07T02:17:10.218Z"}