chatboxai/chatbox · warning · ChatboxCliUsageError

--${name} must be an integer.

Error message

--${name} must be an integer.

What it means

Thrown by integerFlag() in the Chatbox CLI argument parser when a flag's value is not a string matching ^\d+$. This guards CLI integer options (e.g. numeric ports/thresholds) so downstream code receives a valid non-negative integer. Note the regex rejects negative numbers, decimals, and boolean-true (a bare --flag with no value), so all of those shapes trip this guard.

Source

Thrown at src/renderer/packages/chatbox-cli/parser.ts:116

export function stringFlag(parsed: ParsedArguments, name: string): string | undefined {
  const value = parsed.flags.get(name)
  return typeof value === 'string' ? value : undefined
}

export function booleanFlag(parsed: ParsedArguments, name: string): boolean {
  return parsed.flags.get(name) === true
}

export function integerFlag(
  parsed: ParsedArguments,
  name: string,
  options: { defaultValue: number; min: number; max: number }
): number {
  const value = parsed.flags.get(name)
  if (value === undefined) return options.defaultValue
  if (typeof value !== 'string' || !/^\d+$/.test(value)) {
    throw new ChatboxCliUsageError(`--${name} must be an integer.`)
  }
  const result = Number(value)
  if (result < options.min || result > options.max) {
    throw new ChatboxCliUsageError(`--${name} must be between ${options.min} and ${options.max}.`)
  }
  return result
}

View on GitHub (pinned to 81571269ad)

Solutions

1. Pass a plain non-negative integer string for the flag, e.g. `--flag 42`.
2. If a bare flag with no value was intended, the command does not support that shape — supply an explicit integer.
3. If negative or decimal integers are genuinely needed, the regex in parser.ts:116 must be widened — file a change request; do not work around it client-side.

Example fix

// before
chatbox cmd --port
chatbox cmd --limit -1

// after
chatbox cmd --port 8080
chatbox cmd --limit 1

function assertCliInt(raw: unknown, name: string): void {
  if (typeof raw !== 'string' || !/^\d+$/.test(raw)) {
    throw new Error(`Expected --${name} to be a non-negative integer string, got: ${String(raw)}`)
  }
}
// run before invoking the command:
assertCliInt(process.argv portValue, 'port')

function isNonNegIntString(v: unknown): v is string {
  return typeof v === 'string' && /^\d+$/.test(v)
}

try {
  const port = integerFlag(parsed, 'port', { defaultValue: 8080, min: 1, max: 65535 })
} catch (e) {
  if (e instanceof ChatboxCliUsageError) {
    // surface to the CLI user as a usage hint
    console.error(e.message)
    process.exit(2)
  }
  throw e
}

When it happens

Trigger: Calling a CLI command whose definition uses integerFlag() and passing a non-digit value: `chatbox cmd --flag abc`, `chatbox cmd --flag 3.5`, `chatbox cmd --flag -1`, or `chatbox cmd --flag` (no value, parsed as boolean true). The check is `typeof value !== 'string' || !/^\d+$/.test(value)`.

Common situations: User omits the value for an integer flag (parser stores true instead of a string); user passes a negative or fractional number expecting signed/decimal support; a downstream caller programmatically builds the argv string with an empty or NaN value.

Related errors

• --${name} must be between ${options.min} and ${options.max}.
• Missing setting key.
• No authorization code found in the input
• Unterminated quoted argument.
• Unknown or protected setting: ${key}

AI-assisted analysis of chatboxai/chatbox@81571269ad (2026-08-12). Data as JSON: /api/errors/9f3d9d1eeb60c615. Report an issue: GitHub.