vercel/next.js · error · InvalidArgumentError

'${value}' is not a non-negative number.

Error message

'${value}' is not a non-negative number.

What it means

Thrown (as InvalidArgumentError from commander) by parseValidPositiveInteger when a CLI argument value cannot be parsed into a non-negative integer (parseInt yields NaN, Infinity, or a negative number). Used to validate numeric CLI flags like port numbers.

Source

Thrown at packages/next/src/server/lib/utils.ts:285

 * @returns A string with the formatted node options.
 */
export function getFormattedNodeOptionsWithoutInspect() {
  const args = getParsedNodeOptionsWithoutInspect()
  if (Object.keys(args).length === 0) return ''

  return formatNodeOptions(args).nodeOptions
}

/**
 * Check if the value is a valid positive integer and parse it. If it's not, it will throw an error.
 *
 * @param value The value to be parsed.
 */
export function parseValidPositiveInteger(value: string): number {
  const parsedValue = parseInt(value, 10)

  if (isNaN(parsedValue) || !isFinite(parsedValue) || parsedValue < 0) {
    throw new InvalidArgumentError(`'${value}' is not a non-negative number.`)
  }
  return parsedValue
}

export const RESTART_EXIT_CODE = 77

type HeapStatistics = {
  used_heap_size: number
  heap_size_limit: number
}

/**
 * @internal
 */
export function getMemoryRestartStats<T extends HeapStatistics>(
  isDev: boolean,
  devMemoryThresholdRestart: boolean,
  getHeapStatistics: () => T

View on GitHub (pinned to 0ae8c72462)

Solutions

1. Pass a valid non-negative integer to the CLI flag (e.g. --port 3000).
2. If sourcing from an env var, validate/coerce it before forwarding: parseInt and check >= 0.
3. Avoid negative numbers and non-numeric strings for integer CLI flags.

Example fix

// before: non-numeric passed
next start --port abc

// after: valid integer
next start --port 3000

function parsePort(v: string): number {
  const n = parseInt(v, 10)
  if (isNaN(n) || !isFinite(n) || n < 0) throw new Error(`Invalid port: ${v}`)
  return n
}

function isNonNegativeInt(v: string): boolean {
  const n = parseInt(v, 10)
  return !isNaN(n) && isFinite(n) && n >= 0 && String(n) === v
}

null

When it happens

Trigger: A Next.js CLI flag that expects a non-negative integer receives a non-numeric string, a negative number, or an empty string. parseValidPositiveInteger calls parseInt and rejects invalid results.

Common situations: Passing --port abc, --port -1, or a port from an env var that isn't a clean number. Script wrappers that forward unvalidated env values to the CLI.

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