What causes "Could not determine the @next/codemod version." in vercel/next.js?

Reinstall the official next package (npm/pnpm install with the published dist)

vercel/next.js · error · Error

Could not determine the @next/codemod version.

Error message

Could not determine the @next/codemod version.

What it means

When the upgrade requires a version migration, the CLI builds an `npx @next/codemod@<version> upgrade ...` command using the build-time __NEXT_VERSION environment constant. If that env var is not set, the CLI cannot pin a codemod version and throws. This indicates a non-standard or corrupted Next.js build/distribution.

Solutions

Reinstall the official next package (npm/pnpm install with the published dist)
Rebuild next with the standard build (pnpm --filter=next build) so define-env injects __NEXT_VERSION
If running from source, run the full bootstrap build instead of executing unbundled CLI code
Verify with `node -e "console.log(require('next/package.json').version)"` that the install is intact

Example fix

// before: executing src/cli/next-upgrade.ts directly via ts-node
// after: use the built CLI
npx next upgrade --ai

Defensive patterns

Strategy: try-catch

Validate before calling

if (!process.env.__NEXT_VERSION) {
  console.error('__NEXT_VERSION missing; use an official next build')
}

Try / catch

try {
  await spawnNextUpgrade(dir, options)
} catch (e) {
  if (e.message.includes('codemod version')) {
    console.error('Reinstall the official next package: npm i next@latest')
  }
}

Prevention

Use published next builds, not hand-rolled bundles
When building next from source, run pnpm --filter=next build so define-env injects __NEXT_VERSION
Do not strip __NEXT_* define replacements in custom bundler configs

When it happens

Trigger: Running a next build where __NEXT_VERSION was not injected (custom/self-compiled bundles, bundler DCE stripping define-plugin replacement, or a repackaged next distribution missing the define).

Common situations: Using a locally patched or unofficially built next package; running from a source checkout without the taskfile define-env step; environment stripping of __NEXT_* variables.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of vercel/next.js@34433fd12e (2026-09-20). Data as JSON: /api/errors/53ef8141534ba90a. Report an issue: GitHub.

Appendix: source

Thrown at packages/next/src/cli/next-upgrade.ts:246

      const guidePath = join(
        runDirectory,
        'docs/01-app/02-guides/upgrading/agentic-upgrade.md'
      )
      const guidesSpinner = createSpinner('Preparing upgrade')

      try {
        for (const router of ['01-app', '02-pages']) {
          await cp(
            join(bundledDocs, router, '02-guides/upgrading'),
            join(runDirectory, 'docs', router, '02-guides/upgrading'),
            { recursive: true }
          )
        }

        if (needsVersionMigration) {
          const codemodVersion = process.env.__NEXT_VERSION
          if (!codemodVersion) {
            throw new Error('Could not determine the @next/codemod version.')
          }
          const codemodCommand = `${getNpxCommand(baseDir)} @next/codemod@${codemodVersion} upgrade ${result.targetVersion} --yes --skip-adoption${options.verbose ? ' --verbose' : ''}`
          const guide = await readFile(guidePath, 'utf8')
          if (!guide.includes(CODEMOD_COMMAND_PLACEHOLDER)) {
            throw new Error('Could not prepare the upgrade guide.')
          }
          await writeFile(
            guidePath,
            guide.replace(CODEMOD_COMMAND_PLACEHOLDER, codemodCommand)
          )
        }
      } catch (error) {
        await rm(runDirectory, { recursive: true, force: true })
        throw error
      } finally {
        guidesSpinner?.stop()
      }

View on GitHub (pinned to 34433fd12e)