Could not find documentation for Next.js ${tag}. This versio

Error message

Could not find documentation for Next.js ${tag}. This version may not exist on GitHub yet.

What it means

`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).

Source

Thrown at packages/next-codemod/lib/agents-md.ts:217

      await execa(
        'git',
        [
          'clone',
          '--depth',
          '1',
          '--filter=blob:none',
          '--sparse',
          '--branch',
          tag,
          'https://github.com/vercel/next.js.git',
          '.',
        ],
        { cwd: tempDir }
      )
    } catch (error) {
      const message = error instanceof Error ? error.message : String(error)
      if (message.includes('not found') || message.includes('did not match')) {
        throw new Error(
          `Could not find documentation for Next.js ${tag}. This version may not exist on GitHub yet.`
        )
      }
      throw error
    }

    await execa('git', ['sparse-checkout', 'set', 'docs'], { cwd: tempDir })

    const sourceDocsDir = path.join(tempDir, 'docs')
    if (!fs.existsSync(sourceDocsDir)) {
      throw new Error('docs folder not found in cloned repository')
    }

    if (fs.existsSync(destDir)) {
      fs.rmSync(destDir, { recursive: true })
    }
    fs.mkdirSync(destDir, { recursive: true })
    fs.cpSync(sourceDocsDir, destDir, { recursive: true })

View on GitHub (pinned to 0ae8c72462)

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.

Example fix

# before — version has no tag
npx @next/codemod agents-md

# after — pin a real published version, or use bundled docs
npx @next/codemod agents-md --version 15.1.6
git ls-remote --tags https://github.com/vercel/next.js.git | grep v15.1.6

Defensive patterns

Strategy: validation

Validate before calling

// Before running agents-md, confirm the version tag exists on GitHub.
import { execSync } from 'node:child_process'
const ver = require('next/package.json').version
const tag = `v${ver}`
const exists = execSync(`git ls-remote --tags https://github.com/vercel/next.js.git ${tag}`).toString().trim()
if (!exists) throw new Error(`Tag ${tag} not found on GitHub; pin --version`)

Type guard

function isPublishedTag(v: string): boolean {
  return /^\d+\.\d+\.\d+/.test(v) && v !== '0.0.0'
}

Try / catch

try {
  await pullDocs({ cwd })
} catch (e) {
  if (/Could not find documentation/.test(e.message)) {
    console.error('Pin a published version via --version, or use bundled docs (Next 16.2+).')
  }
  throw e
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of vercel/next.js@0ae8c72462 (2026-08-06). Data as JSON: /api/errors/2dfde21351f332f0. Report an issue: GitHub.