vercel/next.js · error · Error

Unsupported AI upgrade type

Error message

Unsupported AI upgrade type ${JSON.stringify(upgradeType)}. Expected "security", "latest", or "future".

What it means

spawnNextUpgrade validates the resolved AI upgrade type before preparing the session. The type comes either from the --ai flag string or from experimental.agenticAutoUpgrade in next.config. Only 'security', 'latest', and 'future' are allowed; anything else is rejected defensively even though resolveAIUpgradeType normally normalizes to 'security'.

Solutions

Use one of --ai, --ai=security, --ai=latest, or --ai=future
Check next.config: experimental.agenticAutoUpgrade must be 'security' | 'latest' | 'future' if set
Run `next upgrade --help` to see accepted values

Example fix

// before
next upgrade --ai=canary
// after
next upgrade --ai=latest

Defensive patterns

Strategy: validation

Validate before calling

const AI_TYPES = ['security','latest','future']
if (!AI_TYPES.includes(aiOption)) {
  throw new Error(`--ai must be one of ${AI_TYPES.join(', ')}`)
}

Type guard

function isAiUpgradeType(v: unknown): v is 'security'|'latest'|'future' {
  return v === 'security' || v === 'latest' || v === 'future'
}

Try / catch

try {
  await spawnNextUpgrade(dir, { ai: opts.ai })
} catch (e) {
  if (String(e.message).includes('Unsupported AI upgrade type')) {
    console.error('Use --ai, --ai=security, --ai=latest, or --ai=future')
  }
}

Prevention

Only pass --ai, --ai=security, --ai=latest, or --ai=future
Validate experimental.agenticAutoUpgrade values against the enum in next.config
Normalize unknown config values to 'security' before invoking

When it happens

Trigger: `next upgrade --ai=<value>` with a value other than security/latest/future (e.g. --ai=canary), or a config value that bypasses normalization.

Common situations: Typo like --ai=secuirty; guessing flag values like --ai=codemap; older docs referencing removed policy names.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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

Appendix: source

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

        })
        return
      }

      // A workspace root must not launch an upgrade for an unspecified app.
      if (!findDir(baseDir, 'app') && !findDir(baseDir, 'pages')) {
        throw new Error(
          'No Next.js app found in this directory. Run the command from an app directory or pass its path.'
        )
      }

      const upgradeType = await resolveAIUpgradeType(baseDir, options.ai)

      if (
        upgradeType !== 'security' &&
        upgradeType !== 'latest' &&
        upgradeType !== 'future'
      ) {
        throw new Error(
          `Unsupported AI upgrade type ${JSON.stringify(upgradeType)}. Expected "security", "latest", or "future".`
        )
      }

      // Resolve the requested target before preparing an agent session.
      const { prepareUpgrade } =
        require('../lib/upgrade/prepare-upgrade') as typeof import('../lib/upgrade/prepare-upgrade')
      const assessmentSpinner = createSpinner('Preparing upgrade')
      const result = await prepareUpgrade(baseDir, upgradeType).finally(() =>
        assessmentSpinner?.stop()
      )

      if (result.status !== 'ready') {
        Log.info(result.reason)
        return
      }

      const needsVersionMigration =

View on GitHub (pinned to 34433fd12e)