vercel/next.js · error

Invalid --top value: ${topRaw}

Error message

Invalid --top value: ${topRaw}

What it means

Thrown by parseArgs (analyze-profiles.ts:74) when the --top value, after Number(), is not finite or is less than 1. The value controls how many hotspots are printed per section (modules, runtime sources, runtime symbols) and is floored to an integer afterward, so zero/negative/non-numeric is rejected as meaningless. Default is 15 when --top is omitted.

Source

Thrown at bench/render-pipeline/analyze-profiles.ts:74

function parseArgs() {
  const rawArgs = process.argv.slice(2)
  if (rawArgs.includes('--help')) {
    usage()
    process.exit(0)
  }

  const args = new Map<string, string>()
  for (const rawArg of rawArgs) {
    if (!rawArg.startsWith('--')) continue
    const [rawKey, rawValue] = rawArg.slice(2).split('=')
    args.set(rawKey, rawValue ?? 'true')
  }

  const topRaw = args.get('top')
  const top = topRaw ? Number(topRaw) : 15
  if (!Number.isFinite(top) || top < 1) {
    throw new Error(`Invalid --top value: ${topRaw}`)
  }

  return {
    artifactDirArg: args.get('artifact-dir'),
    top: Math.floor(top),
  }
}

async function exists(path: string): Promise<boolean> {
  try {
    await access(path, constants.F_OK)
    return true
  } catch {
    return false
  }
}

async function resolveArtifactRunDir(artifactDirArg?: string): Promise<string> {

View on GitHub (pinned to 0ae8c72462)

Solutions

1. Pass a positive integer: --top=15 (default) or any N >= 1.
2. If you used a bare --top, add =N; bare flags resolve to 'true' here.
3. There is intentionally no 'unlimited' option; pick a large N (e.g. 100) instead of 0.
4. Wrap the value through a numeric check in calling scripts before invoking analyze.

Example fix

// before
//   pnpm bench:render-pipeline:analyze --top=0
//   pnpm bench:render-pipeline:analyze --top

// after
//   pnpm bench:render-pipeline:analyze --top=30

function parseTop(raw: string | undefined): number {
  const n = raw ? Number(raw) : 15
  if (!Number.isInteger(n) || n < 1) {
    throw new Error(`--top must be a positive integer (got ${raw ?? 'unset'})`)
  }
  return n
}

function isPositiveIntegerString(s: string): boolean {
  const n = Number(s)
  return Number.isInteger(n) && n >= 1
}

// CLI validation failure is fatal and clear; typically don't catch. If scripting:
try {
  parseArgs()
} catch (err) {
  console.error((err as Error).message, '\nUsage: --top=<positive integer>')
  process.exit(2)
}

When it happens

Trigger: Running `pnpm bench:render-pipeline:analyze --top=<x>` with x being non-numeric (abc, empty after =), Infinity-ish (e.g. a bare --top with no value yields 'true' -> NaN), zero, or negative. Number('') is 0 and fails the < 1 check; Number('true') is NaN and fails !isFinite.

Common situations: Passing --top with no value (--top instead of --top=15, which makes rawValue undefined -> 'true' -> NaN); passing 0 expecting 'show all' (the script has no 'all' sentinel); a wrapper script forwarding an unbound variable.

Related errors

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

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