What causes "docs folder not found in cloned repository" in vercel/next.js?

Use a newer tag that definitely has a top-level `docs/` folder, or pass a version override with a known-good tag.

docs folder not found in cloned repository

Error message

docs folder not found in cloned repository

What it means

After `agents-md` successfully clones the repo at the version tag, it runs `git sparse-checkout set docs` and then asserts the `docs/` folder exists in the working tree. If it doesn't, this error is thrown. It indicates the clone succeeded but the sparse checkout produced no `docs` directory — e.g. the tag predates the `docs/` folder, the sparse-checkout filter mis-fired, or the repo layout at that tag differs from current.

Source

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

          '.',
        ],
        { 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 })
  } finally {
    if (fs.existsSync(tempDir)) {
      fs.rmSync(tempDir, { recursive: true })
    }
  }
}

export function collectDocFiles(dir: string): { relativePath: string }[] {
  return (fs.readdirSync(dir, { recursive: true }) as string[])
    .filter(
      (f) =>

View on GitHub (pinned to 0ae8c72462)

Solutions

Use a newer tag that definitely has a top-level `docs/` folder, or pass a version override with a known-good tag.
Prefer the bundled docs path (Next 16.2+) which reads from `node_modules/next/dist/docs` and avoids cloning.
Verify git supports sparse-checkout (`git sparse-checkout list`) and rerun.
Manually clone `--branch <tag>` and confirm `docs/` exists to identify tag/layout issues.

Example fix

# verify the tag has a docs folder
git clone --depth 1 --branch v15.1.6 https://github.com/vercel/next.js.git /tmp/njs && ls /tmp/njs/docs
# if missing, pick a newer tag or use bundled docs
npx @next/codemod agents-md --version 16.2.0

Defensive patterns

Strategy: validation

Validate before calling

// Pre-check the tag has a docs folder by listing the sparse tree.
import { execSync } from 'node:child_process'
const out = execSync(`git ls-remote --tags https://github.com/vercel/next.js.git v${ver}`).toString()
if (!out) throw new Error('Tag missing; pick a newer version with docs/')

Try / catch

try {
  await cloneDocsFolder(tag, dest)
} catch (e) {
  if (/docs folder not found/.test(e.message)) {
    console.error('Use a newer tag or bundled docs.')
  }
  throw e
}

Prevention

Prefer bundled docs (Next 16.2+) to avoid clone layout issues.
Pin a known-good version tag.
Confirm local git supports sparse-checkout.

When it happens

Trigger: Running `agents-md` against an old tag whose repository structure didn't include a top-level `docs/` folder; a git/fs hiccup where sparse-checkout left an empty worktree; disk/permission errors during checkout.

Common situations: Very old Next.js versions where docs lived elsewhere; transient filesystem/git errors in CI; sparse-checkout version mismatch on the git binary available.

Related errors

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