What causes "--timeout must be a positive integer (seconds)" in jackwener/OpenCLI?

Pass a positive whole number of seconds, e.g. --timeout 30.

jackwener/OpenCLI · error · ArgumentError

--timeout must be a positive integer (seconds)

Error message

--timeout must be a positive integer (seconds)

What it means

requirePositiveTimeout validates that the --timeout option is an integer greater than zero before it is used to drive page waits in the ChatWise CLI. ArgumentError is thrown when the value is a non-integer or non-positive number, so bad user input fails immediately with a clear message.

Source

Thrown at clis/chatwise/utils.js:9

import { ArgumentError } from '@jackwener/opencli/errors';

export const MESSAGE_WRAPPER_SELECTOR = '[class*="group/message"]';
export const MIN_COMPOSER_SCORE = 120;

export function requirePositiveTimeout(value) {
    const timeout = value;
    if (!Number.isInteger(timeout) || timeout <= 0) {
        throw new ArgumentError('--timeout must be a positive integer (seconds)');
    }
    return timeout;
}

export function scoreChatwiseComposerCandidate(candidate, viewportHeight = 0) {
    if (candidate.hidden) return -1000;

    let score = 0;
    const normalizedRole = String(candidate.role || '').toLowerCase();
    if (normalizedRole === 'textbox') score += 10;

    const normalizedClasses = `${candidate.classes || ''} ${candidate.editorClasses || ''} ${candidate.ariaLabel || ''}`.toLowerCase();
    if (normalizedClasses.includes('cm-content')) score += 20;
    if (normalizedClasses.includes('cm-editor')) score += 30;
    if (normalizedClasses.includes('simple-editor')) score -= 140;

    const searchableText = `${candidate.placeholder || ''} ${candidate.ariaLabel || ''} ${candidate.text || ''}`.toLowerCase();
    if (searchableText.includes('enter a message here')) score += 220;

View on GitHub (pinned to 49907e53dc)

Solutions

Pass a positive whole number of seconds, e.g. --timeout 30.
Check the script or variable feeding --timeout for empty values or non-numeric strings.
If sub-second precision is needed, it is unsupported — use the minimum of 1 second and adjust other waits.

Example fix

// before
clis chatwise ask "hi" --timeout 0.5
// after
clis chatwise ask "hi" --timeout 5

Defensive patterns

Strategy: validation

Validate before calling

const n = Number(timeoutArg);
if (!Number.isInteger(n) || n <= 0) throw new Error('--timeout must be a positive integer (seconds)');

Type guard

function isPositiveInt(v) { return Number.isInteger(v) && v > 0; }

Try / catch

try {
  runChatwiseAsk({ timeout: parsedTimeout });
} catch (err) {
  if (err instanceof ArgumentError) {
    console.error('Usage: --timeout <positive integer seconds>, e.g. --timeout 60');
  } else throw err;
}

Prevention

Validate timeout arguments at CLI parse time
Never compute timeouts with arithmetic that can yield 0 or NaN
Document the option as integer seconds in help text

When it happens

Trigger: Passing --timeout 0, a negative number, a float like 1.5, or a value that was coerced to NaN (e.g. --timeout "abc" parsed to a number) into the timeout() helper, which delegates to requirePositiveTimeout.

Common situations: Copy-pasting a shell snippet with an empty --timeout value; scripts computing the timeout with arithmetic that yields 0 or NaN; users expecting sub-second timeouts and passing 0.5.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

AI-assisted analysis of jackwener/OpenCLI@49907e53dc (2026-08-29). Data as JSON: /api/errors/c7cb52952c6dfd3c. Report an issue: GitHub.