vercel/next.js · error

--cpu-throttle must be at least 1, got ${cpuThrottle}

Error message

--cpu-throttle must be at least 1, got ${cpuThrottle}

What it means

Thrown by parseCli when --cpu-throttle is less than 1. The value is passed directly to Chrome DevTools Protocol CPU throttling (Emulation.setCPUThrottlingRate), which rejects rates below 1 (1 = no throttling). Validating here gives a clear message instead of a cryptic CDP error.

Source

Thrown at bench/render-pipeline/client-trace.ts:180

    .map((route) => route.trim())
    .filter(Boolean)
  if (routes.length === 0) {
    throw new Error('--routes cannot be empty')
  }
  for (const route of routes) {
    if (!route.startsWith('/')) {
      throw new Error(`Each route must start with '/': ${route}`)
    }
  }

  const samples = parseNumberArg(args, 'samples', 3)
  if (samples < 1) {
    throw new Error(`--samples must be at least 1, got ${samples}`)
  }
  // CDP rejects rates below 1 (1 = no throttling).
  const cpuThrottle = parseNumberArg(args, 'cpu-throttle', 4)
  if (cpuThrottle < 1) {
    throw new Error(`--cpu-throttle must be at least 1, got ${cpuThrottle}`)
  }

  const timestamp = new Date().toISOString().replace(/[:.]/g, '-')

  return {
    appDir: resolve(REPO_ROOT, args.get('app-dir') ?? 'bench/basic-app'),
    routes,
    samples,
    cpuThrottle,
    build: parseBoolean(args.get('build') ?? 'false'),
    startServer: parseBoolean(args.get('start-server') ?? 'true'),
    port: parseNumberArg(args, 'port', 3199),
    timeoutMs: parseNumberArg(args, 'timeout-ms', 30_000),
    settleMs: parseNumberArg(args, 'settle-ms', 750),
    artifactDir: resolve(
      REPO_ROOT,
      args.get('artifact-dir') ??
        `bench/render-pipeline/artifacts/${timestamp}-client`

View on GitHub (pinned to 0ae8c72462)

Solutions

1. Pass --cpu-throttle=1 to disable throttling (no slowdown).
2. Pass a value > 1 (e.g. 4, the default) to slow the CPU by that factor.

Example fix

// before (intended: no throttle)
--cpu-throttle=0
// after
--cpu-throttle=1

// 1 means no throttling; enforce >= 1
const cpuThrottle = Math.max(1, parseNumberArg(args, 'cpu-throttle', 4))

null

null

When it happens

Trigger: Passing --cpu-throttle=0, --cpu-throttle=-2, or --cpu-throttle=0.5.

Common situations: Confusing the throttle rate with a percentage; intending 'no throttle' and passing 0 instead of 1; a typo.

Related errors

• Invalid --top value: ${topRaw}
• Invalid numeric value for --${key}: ${value}
• --routes cannot be empty
• Each route must start with '/': ${route}
• Invalid --scenario value: ${scenarioRaw}. Use e2e|minimal-se

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