What causes "Invalid value for --${name}: ${raw}" in chenglou/pretext?

Pass bare integers in the unit the script expects (pixels for start/end/step, ms for timeout).

chenglou/pretext · error · Error

Invalid value for --${name}: ${raw}

Error message

Invalid value for --${name}: ${raw}

What it means

Thrown by parseNumberFlag in corpus-font-matrix.ts — the font-matrix counterpart of [26]. Required numeric flags (start, end, step, port, timeout) route through it; a present-but-non-numeric value aborts the script at module top-level. Identical contract to [26]: present-but-NaN throws, but parseInt's prefix rule means `--start=300px` silently parses as 300.

Source

Thrown at scripts/corpus-font-matrix.ts:332

      label: 'Geeza Pro',
      font: '20px "Geeza Pro", "Noto Nastaliq Urdu", serif',
      lineHeight: 34,
    },
  ],
}

function parseStringFlag(name: string): string | null {
  const prefix = `--${name}=`
  const arg = process.argv.find(value => value.startsWith(prefix))
  return arg === undefined ? null : arg.slice(prefix.length)
}

function parseNumberFlag(name: string, fallback: number): number {
  const raw = parseStringFlag(name)
  if (raw === null) return fallback
  const parsed = Number.parseInt(raw, 10)
  if (!Number.isFinite(parsed)) {
    throw new Error(`Invalid value for --${name}: ${raw}`)
  }
  return parsed
}

function parseOptionalNumberFlag(name: string): number | null {
  const raw = parseStringFlag(name)
  if (raw === null) return null
  const parsed = Number.parseInt(raw, 10)
  if (!Number.isFinite(parsed)) {
    throw new Error(`Invalid value for --${name}: ${raw}`)
  }
  return parsed
}

function parseBrowser(value: string | null): BrowserKind {
  const browser = (value ?? process.env['CORPUS_CHECK_BROWSER'] ?? 'chrome').toLowerCase()
  if (browser !== 'chrome' && browser !== 'safari') {
    throw new Error(`Unsupported browser ${browser}; expected chrome or safari`)

View on GitHub (pinned to ac49b09b7d)

Solutions

Pass bare integers in the unit the script expects (pixels for start/end/step, ms for timeout).
Strip units before passing: `--start=${WIDTH%p}` if shell-quoting a value with a suffix.
Remember parseInt is permissive — units AFTER a leading number are silently dropped, not flagged.

Example fix

// before
bun run scripts/corpus-font-matrix.ts --id=ja-kumo-no-ito --step=ten
// after
bun run scripts/corpus-font-matrix.ts --id=ja-kumo-no-ito --step=10

Defensive patterns

Strategy: validation

Validate before calling

function strictIntFlag(name: string, raw: string | null, fallback: number): number {
  if (raw === null) return fallback
  if (!/^-?\d+$/.test(raw)) throw new Error(`--${name} expects an integer, got ${JSON.stringify(raw)}`)
  return Number.parseInt(raw, 10)
}

Type guard

function isStrictInteger(value: string): boolean {
  return /^-?\d+$/.test(value)
}

Prevention

Pass bare integers in the unit the script expects (px for start/end/step, ms for timeout).
Strip units before passing: parseInt silently drops a trailing suffix.
Use a strict regex if full-string rejection matters — the built-in parseNumberFlag is permissive.

When it happens

Trigger: parseStringFlag finds `--start=`, `--end=`, `--step=`, `--port=`, or `--timeout=` with a value whose leading characters are non-numeric. Throw on `--step=ten`, `--start=wide`, `--port=`, `--end=`. Note `--start=300px` does NOT throw (parseInt returns 300).

Common situations: Passing widths with units (`--start=300px`), words for step (`--step=ten`), empty values from an unset env var; copying example invocations from documentation that used a different flag syntax.

Related errors

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