Issue Station
Sign In
Tools hereToolbox

nextjs - ✅(Solved) Fix agents-md does not detect version properly if ranges are used [2 pull requests, 1 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
vercel/next.js#89773•Fetched 2026-04-08 00:21:22
View on GitHub
Comments
1
Participants
2
Timeline
6
Reactions
0
Author
emontyemonty
Participants
emontyemontyHybridGeneuis1HybridGeneuis1
Timeline (top)
cross-referenced ×2referenced ×2commented ×1issue_type_added ×1

Fix Action

Fixed

PR fix notes

PR #89774: fix(codemod): ensure agent instruction is executable

Description (problem / solution / changelog)

In the current form, the agents-md command writes an instruction that doesn't actually execute, since the command is only on @canary.

What?

In the current form, the agents-md command writes an instruction that doesn't actually execute. There are two issues. One is that it writes the instruction without @canary and it only exists in canary right now. The second is that, without embedding a version in the instruction, it does version inference logic and in the case of a version range, the command fails.

Why?

I work with agents running in their own sandboxes, not on my laptop where I have done out of band setup work. So the agent needs to be able to clone the repo and do necessary steps from AGENTS.md for things to work.

How?

Fixes #89772 Fixes #89773

Capture the invocation details when it is run and write the instructions to AGENTS.md so that the original command will be re-run.

For the version issue, look for a version in package-lock.json which should always have the correct and precise version.

Changed files

  • packages/next-codemod/bin/agents-md.ts (modified, +8/-0)
  • packages/next-codemod/lib/__tests__/agents-md-unit.test.js (added, +270/-0)
  • packages/next-codemod/lib/agents-md.ts (modified, +46/-2)

PR #90067: fix(codemod): handle semver ranges in agents-md version detection

Description (problem / solution / changelog)

What?

Fix agents-md codemod failing when Next.js version is specified as a semver range in package.json (e.g. ^16, ~16.1.0) and the package is not yet installed.

Why?

getNextjsVersion() only detects the installed version via require.resolve('next/package.json'). When Next.js isn't installed yet (common when running the codemod for the first time, or when an AI agent re-runs the generated command in a fresh sandbox), the function returns null and the codemod fails with:

Could not find documentation for Next.js v16. This version may not exist on GitHub yet.

How?

Added a fallback in getNextjsVersion() that reads the version range from package.json dependencies and extracts a concrete version using a new exported extractVersionFromRange() helper:

  • ^16.1.3 → 16.1.3
  • ~16.1.0 → 16.1.0
  • ^16 → 16.0.0
  • >=15.0.0 → 15.0.0
  • ^16.2.0-canary.16 → 16.2.0-canary.16

The fallback is only used when require.resolve fails and monorepo detection finds nothing.

Checklist

  • Related issues linked using fixes #number
  • Tests added
  • Errors have a helpful link attached — N/A (no new error messages)

Fixes #89773 Fixes #89772

Changed files

  • packages/next-codemod/lib/__tests__/agents-md.test.js (added, +128/-0)
  • packages/next-codemod/lib/agents-md.ts (modified, +64/-12)

Code Example

$ npx @next/codemod@canary agents-md --output AGENTS.md

Downloading Next.js 16 documentation to .next-docs...
Failed to pull docs: Could not find documentation for Next.js v16. This version may not exist on GitHub yet.

---

Operating System:
  Platform: linux
  Arch: x64
  Version: #12-Ubuntu SMP PREEMPT_DYNAMIC Fri Jan  9 20:46:52 UTC 2026
  Available memory (MB): 31021
  Available CPU cores: 22
Binaries:
  Node: 24.12.0
  npm: 11.6.2
  Yarn: N/A
  pnpm: N/A
Relevant Packages:
  next: 16.1.6 // Latest available version is detected (16.1.6).
  eslint-config-next: N/A
  react: 19.2.4
  react-dom: 19.2.4
  typescript: 5.9.3
Next.js Config:
  output: standalone
RAW_BUFFERClick to expand / collapse

Link to the code that reproduces this issue

https://codesandbox.io/p/sandbox/optimistic-star-2nq57m

To Reproduce

Run npx @next/codemod@canary agents-md --output AGENTS.md in a repo with a range provided for next.

Current vs. Expected behavior

If I run npx @next/codemod@canary agents-md --output AGENTS.md in a repo using ^16 for next, the code detects version 16 and tries to download it, which is both incorrect and does not work:

$ npx @next/codemod@canary agents-md --output AGENTS.md

Downloading Next.js 16 documentation to .next-docs...
Failed to pull docs: Could not find documentation for Next.js v16. This version may not exist on GitHub yet.

Provide environment information

Operating System:
  Platform: linux
  Arch: x64
  Version: #12-Ubuntu SMP PREEMPT_DYNAMIC Fri Jan  9 20:46:52 UTC 2026
  Available memory (MB): 31021
  Available CPU cores: 22
Binaries:
  Node: 24.12.0
  npm: 11.6.2
  Yarn: N/A
  pnpm: N/A
Relevant Packages:
  next: 16.1.6 // Latest available version is detected (16.1.6).
  eslint-config-next: N/A
  react: 19.2.4
  react-dom: 19.2.4
  typescript: 5.9.3
Next.js Config:
  output: standalone

Which area(s) are affected? (Select all that apply)

Not sure

Which stage(s) are affected? (Select all that apply)

next dev (local)

Additional context

No response

extent analysis

Quick Fix

Clamp the detected Next.js version to the highest documentation‑available major (v15) and add a --next-version override flag.

1️⃣ Patch the codemod (agents‑md)

// src/agents-md.ts (or wherever the version is resolved)

import semver from 'semver';
import { execSync } from 'child_process';

// ---- Existing logic ----
// const pkg = JSON.parse(execSync('npm view next version --json').toString());
// const detected = pkg.version;   // e.g. "16.1.6"

// ---- New logic -------------------------------------------------
const MAX_DOCS_MAJOR = 15;               // docs exist up to v15
let targetVersion = detected;

// Allow user override:  npx @next/codemod@canary agents-md --next-version 14
const argv = process.argv;
const overrideIdx = argv.findIndex(v => v === '--next-version');
if (overrideIdx !== -1 && argv[overrideIdx + 1]) {
  targetVersion = argv[overrideIdx + 1];
}

// If the

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#ssr#installation#tensor shape#autograd error#memory leak#API versioning#request timeout

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING