vercel/next.js · error

Invalid numeric value for --${key}: ${value}

Error message

Invalid numeric value for --${key}: ${value}

What it means

Thrown by parseNumberArg in the client-trace CLI when a numeric flag (--samples, --cpu-throttle, --port, --timeout-ms, --settle-ms) receives a value that Number() parses to NaN or Infinity. This is a CLI argument validation guard that fails fast with a precise message instead of letting a non-finite number propagate into Chrome DevTools Protocol calls or fetch logic.

Source

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

      documentLoaderURL?: string
    }
  }
}

function parseBoolean(value: string): boolean {
  return value === '1' || value === 'true' || value === 'yes'
}

function parseNumberArg(
  args: Map<string, string>,
  key: string,
  fallback: number
): number {
  const value = args.get(key)
  if (value === undefined) return fallback
  const parsed = Number(value)
  if (!Number.isFinite(parsed)) {
    throw new Error(`Invalid numeric value for --${key}: ${value}`)
  }
  return parsed
}

function usage() {
  console.log(`Usage: pnpm bench:render-pipeline:client [options]

Options:
  --app-dir=<path>            (default: bench/basic-app)
  --routes=/,/dashboard,...   (default: /,/dashboard,/docs,/blog,/tailwind)
  --samples=<number>          (default: 3)
  --cpu-throttle=<number>     (default: 4) CDP CPU throttling rate
  --build=true|false          (default: false) build the fixture first
  --start-server=true|false   (default: true) set false to attach to a
                              server already running on --port
  --port=<number>             (default: 3199)
  --timeout-ms=<number>       (default: 30000)
  --settle-ms=<number>        (default: 750) post-hydration wait so

View on GitHub (pinned to 0ae8c72462)

Solutions

1. Pass a plain finite integer for the flagged option, e.g. --samples=3.
2. Re-run with --help to see the expected value types for each flag.
3. Check shell quoting if the value comes from a variable.

Example fix

// before
--port=:3199
// after
--port=3199

// Validate numeric CLI args before passing them
function assertFiniteInt(label: string, v: unknown): number {
  const n = Number(v)
  if (!Number.isFinite(n)) throw new Error(`--${label} must be a finite number, got ${v}`)
  return n
}

const isFiniteNumber = (v: unknown): v is number =>
  typeof v === 'number' && Number.isFinite(v)

null

When it happens

Trigger: Passing --samples=abc, --port=:3000, --cpu-throttle=fast, an empty value like --samples=, or a value with stray characters.

Common situations: Typo in a flag value; copy-pasting a URL-style port; passing a unit suffix the parser does not strip; shell quoting that drops the value.

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/2b61192ee1e357df. Report an issue: GitHub.