--tail-lines must be an integer between 100 and 1000. ${SPAR

Error message

--tail-lines must be an integer between 100 and 1000.
${SPARKSHELL_USAGE}

What it means

The value given to --tail-lines (space-separated form) failed range validation: parseInt did not yield a finite integer or the integer is outside the 100-1000 window enforced by the CLI.

Source

Thrown at src/cli/sparkshell.ts:348

    if (token === '--tmux-pane') {
      const next = args[index + 1];
      if (!next || next.startsWith('-')) throw new Error(`--tmux-pane requires a pane id.\n${SPARKSHELL_USAGE}`);
      paneId = next;
      index += 1;
      continue;
    }
    if (token.startsWith('--tmux-pane=')) {
      const value = token.slice('--tmux-pane='.length).trim();
      if (!value) throw new Error(`--tmux-pane requires a pane id.\n${SPARKSHELL_USAGE}`);
      paneId = value;
      continue;
    }
    if (token === '--tail-lines') {
      const next = args[index + 1];
      if (!next || next.startsWith('-')) throw new Error(`--tail-lines requires a numeric value.\n${SPARKSHELL_USAGE}`);
      const parsed = Number.parseInt(next, 10);
      if (!Number.isFinite(parsed) || parsed < 100 || parsed > 1000) {
        throw new Error(`--tail-lines must be an integer between 100 and 1000.\n${SPARKSHELL_USAGE}`);
      }
      tailLines = parsed;
      sawTailLines = true;
      index += 1;
      continue;
    }
    if (token.startsWith('--tail-lines=')) {
      const parsed = Number.parseInt(token.slice('--tail-lines='.length), 10);
      if (!Number.isFinite(parsed) || parsed < 100 || parsed > 1000) {
        throw new Error(`--tail-lines must be an integer between 100 and 1000.\n${SPARKSHELL_USAGE}`);
      }
      tailLines = parsed;
      sawTailLines = true;
      continue;
    }
    throw new Error(`tmux pane mode does not accept an additional command.\n${SPARKSHELL_USAGE}`);
  }

View on GitHub (pinned to 3ad79a8a6f)

Solutions

Pick an integer within 100-1000, e.g. `--tail-lines 200`
Omit the flag entirely to accept the default of 200 lines

Example fix

# before
sparkshell --tmux-pane 0 --tail-lines 50
# after
sparkshell --tmux-pane 0 --tail-lines 200

Defensive patterns

Strategy: validation

Validate before calling

function toTailLines(v: string): number {
  const n = Number.parseInt(v, 10);
  if (!Number.isInteger(n) || n < 100 || n > 1000) throw new RangeError(`--tail-lines must be 100-1000, got ${v}`);
  return n;
}

Prevention

Clamp UI/script inputs to 100-1000 before passing
Remember the default is 200 — usually you can omit the flag

When it happens

Trigger: `sparkshell --tmux-pane 0 --tail-lines 50`, `--tail-lines 5000`, or `--tail-lines 12.5` (parseInt truncates but then range checks apply).

Common situations: Users assuming any positive number is accepted; copying a large tail size from another tool's config; defaults drift after the allowed range changed.

Related errors

AI-assisted analysis of Yeachan-Heo/oh-my-codex@3ad79a8a6f (2026-08-27). Data as JSON: /api/errors/362fa7c64c2ee6f4. Report an issue: GitHub.