vercel/next.js · error

--samples must be at least 1, got ${samples}

Error message

--samples must be at least 1, got ${samples}

What it means

Thrown by parseCli when --samples is less than 1. The tracer collects per-route performance traces and needs at least one sample per route to produce any output; zero or negative samples would yield an empty trace file and meaningless aggregates.

Source

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

    }
  }

  const routes = (args.get('routes') ?? '/,/dashboard,/docs,/blog,/tailwind')
    .split(',')
    .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),

View on GitHub (pinned to 0ae8c72462)

Solutions

1. Pass --samples=1 or higher (default is 3).
2. For more stable traces, increase samples rather than lowering below 1.

Example fix

// before
--samples=0
// after
--samples=3

const samples = Math.max(1, parseNumberArg(args, 'samples', 3))

null

null

When it happens

Trigger: Passing --samples=0, --samples=-1, or --samples=0.5 (which floors to 0 in some downstream logic).

Common situations: A script defaults samples to 0 when unset; a typo; misunderstanding that 1 is the minimum.

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