jackwener/OpenCLI · error · ArgumentError

--timeout must be a positive integer (seconds)

Error message

--timeout must be a positive integer (seconds)

What it means

The gemini ask command in clis/gemini/ask.js requires `--timeout` to be an integer number of seconds >= 1. If kwargs.timeout is not an integer (float, string, 0, negative, or missing-but-nonstandard) this ArgumentError is thrown before any browser automation starts.

Source

Thrown at clis/gemini/ask.js:102

    domain: GEMINI_DOMAIN,
    strategy: Strategy.COOKIE,
    browser: true,
    siteSession: 'persistent',
    navigateBefore: false,
    defaultFormat: 'plain',
    args: [
        { name: 'prompt', required: true, positional: true, help: 'Prompt to send' },
        { name: 'model', type: 'string', required: false, help: 'Gemini model to use (e.g. "2.5-flash"). Use "opencli gemini models" to list available values.' },
        { name: 'timeout', type: 'int', required: false, help: 'Max seconds to wait (default: 60)', default: 60 },
        { name: 'new', required: false, help: 'Start a new chat first (true/false, default: false)', default: 'false' },
        { name: 'thinking', required: false, help: 'Thinking level: standard or extended (omitted = leave unchanged)', default: null },
    ],
    columns: ['response'],
    func: async (page, kwargs) => {
        const prompt = kwargs.prompt;
        const timeout = kwargs.timeout;
        if (!Number.isInteger(timeout) || timeout < 1) {
            throw new ArgumentError('--timeout must be a positive integer (seconds)');
        }

        // ── New chat (must happen before model/thinking selection) ──────
        const startFresh = normalizeBooleanFlag(kwargs.new);
        if (startFresh)
            await startNewGeminiChat(page);

        // ── Early validation: model format & thinking value ────────────
        const hasModel = kwargs.model !== undefined && kwargs.model !== null;
        const hasThinking = kwargs.thinking != null;

        let modelValue = null;
        if (hasModel) {
            modelValue = String(kwargs.model).trim();
            validateAskModelValue(modelValue);
        }

        if (hasThinking) {

View on GitHub (pinned to 49907e53dc)

Solutions

1. Pass a whole number of seconds >= 1: `--timeout 60`
2. Convert milliseconds to seconds if you have an ms value (30000 -> 30)
3. Remove quotes from the value in shell scripts so it parses as a number
4. Omit --timeout entirely if the command supports a default

Example fix

// before
opencli gemini ask --timeout 30000 ...
// after
opencli gemini ask --timeout 30 ...

const t = Number(args.timeout);
if (!Number.isInteger(t) || t < 1) {
  throw new Error('--timeout must be a positive integer (seconds)');
}

function isValidTimeout(v) {
  return Number.isInteger(v) && v >= 1;
}

try {
  await geminiAsk(args);
} catch (err) {
  if (err.name === 'ArgumentError' && err.message.includes('--timeout')) {
    return geminiAsk({ ...args, timeout: Math.max(1, Math.round(Number(args.timeout) / 1000) || 30) });
  }
  throw err;
}

When it happens

Trigger: `opencli gemini ask --timeout 0`, `--timeout -5`, `--timeout 2.5`, or `--timeout "30"` (string rather than number, if the CLI doesn't coerce).

Common situations: Passing fractional seconds expecting millisecond or sub-second precision; zero meant 'no timeout'; quoting the value in a shell wrapper; unit confusion (ms vs seconds).

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

• ocr-wait-seconds must be a non-negative integer: ${raw}
• --timeout must be an integer >= 30 seconds
• <train-no> "${trainNo}" does not look like a 12306 internal
• --from station must not be empty
• --to station must not be empty

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