What causes "Invalid value for --runs: ${runs}; expected an integer >= 1" in chenglou/pretext?

Use --runs=1 or higher (e.g. --runs=5 for a stable median).

chenglou/pretext · error · Error

Invalid value for --runs: ${runs}; expected an integer >= 1

Error message

Invalid value for --runs: ${runs}; expected an integer >= 1

What it means

Thrown at benchmark-check.ts:257-259 after parsing the --runs flag (or BENCHMARK_CHECK_RUNS env, default 3). Even though parseNumberFlag already rejected non-finite values (error 6), this additional check requires runs to be a positive integer (Number.isInteger AND >= 1). It catches cases where parseInt produced a finite-but-invalid number like 0 or a negative. Because the env fallback path can produce NaN from an empty BENCHMARK_CHECK_RUNS, this guard also catches that leaked NaN.

Source

Thrown at scripts/benchmark-check.ts:258

  }

  if ((report.corpusResults ?? []).length > 0) {
    console.log('Long-form corpus stress:')
    for (const corpus of report.corpusResults!) {
      console.log(
        `  ${corpus.label}: analyze ${corpus.analysisMs.toFixed(2)}ms | measure ${corpus.measureMs.toFixed(2)}ms | prepare ${corpus.prepareMs.toFixed(2)}ms | layout ${corpus.layoutMs < 0.01 ? '<0.01' : corpus.layoutMs.toFixed(2)}ms | ${corpus.analysisSegments.toLocaleString()}→${corpus.segments.toLocaleString()} segs | ${corpus.lineCount} lines @ ${corpus.width}px`,
      )
    }
  }
}

const browser = parseBrowser(parseStringFlag('browser'))
const requestedPort = parseNumberFlag('port', Number.parseInt(process.env['BENCHMARK_CHECK_PORT'] ?? '0', 10))
const runs = parseNumberFlag('runs', Number.parseInt(process.env['BENCHMARK_CHECK_RUNS'] ?? '3', 10))
const output = parseStringFlag('output')

if (!Number.isInteger(runs) || runs < 1) {
  throw new Error(`Invalid value for --runs: ${runs}; expected an integer >= 1`)
}

let serverProcess: ChildProcess | null = null
const lock = await acquireBrowserAutomationLock(browser)
const session = createBrowserSession(browser, { foreground: true })

try {
  const port = await getAvailablePort(requestedPort === 0 ? null : requestedPort)
  const pageServer = await ensurePageServer(port, '/benchmark', process.cwd())
  serverProcess = pageServer.process
  const baseUrl = `${pageServer.baseUrl}/benchmark`

  const reports: BenchmarkReport[] = []
  for (let runIndex = 0; runIndex < runs; runIndex++) {
    const requestId = `${Date.now()}-${runIndex}-${Math.random().toString(36).slice(2)}`
    const url =
      `${baseUrl}?report=1` +
      `&requestId=${encodeURIComponent(requestId)}`

View on GitHub (pinned to ac49b09b7d)

Solutions

Use --runs=1 or higher (e.g. --runs=5 for a stable median).
If BENCHMARK_CHECK_RUNS is templated, default it: BENCHMARK_CHECK_RUNS="${BENCHMARK_CHECK_RUNS:-3}".
Audit the env for an empty BENCHMARK_CHECK_RUNS assignment.
Do not pass fractional or zero values; the harness needs at least one run.

Example fix

# before
export BENCHMARK_CHECK_RUNS=

# after
unset BENCHMARK_CHECK_RUNS   # uses default 3
# or
export BENCHMARK_CHECK_RUNS=5

Defensive patterns

Strategy: validation

Validate before calling

// Validate runs explicitly before the script's own check.
const runs = parseNumberFlag('runs', Number.parseInt(process.env.BENCHMARK_CHECK_RUNS ?? '3', 10))
if (!Number.isInteger(runs) || runs < 1) {
  throw new Error(`Invalid value for --runs: ${runs}; expected an integer >= 1`)
}

Type guard

function isPositiveInteger(value: number): boolean {
  return Number.isInteger(value) && value >= 1
}

Prevention

Default BENCHMARK_CHECK_RUNS with parameter expansion: BENCHMARK_CHECK_RUNS="${BENCHMARK_CHECK_RUNS:-3}".
Never pass --runs=0; use --runs=1 for a single-shot benchmark.
Audit env files for empty BENCHMARK_CHECK_RUNS assignments (parseInt('') is NaN).

When it happens

Trigger: Passing --runs=0, --runs=-2, or exporting BENCHMARK_CHECK_RUNS= (empty string, which parseInts to NaN and bypasses parseNumberFlag's finite check via the fallback path). Note: --runs=2.5 parses to 2 via parseInt and would PASS both checks (a known leniency). Only truly non-positive or non-integer (NaN) values are rejected here.

Common situations: Wanting 'no repeats' and guessing --runs=0; a CI template setting BENCHMARK_CHECK_RUNS='' ; a negative value from an arithmetic expression; an off-by-one in a wrapper script computing runs from a count.

Related errors

AI-assisted analysis of chenglou/pretext@ac49b09b7d (2026-08-12). Data as JSON: /api/errors/8e8eee1ae7733651. Report an issue: GitHub.