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 deep-research-result CLI command validates its --timeout option and throws ArgumentError when it is not an integer >= 1 (seconds). The library intentionally rejects fractional, zero, negative, and non-numeric values because the timeout is used directly as a wait duration in seconds. This fail-fast validation prevents silent hangs or invalid browser waits later in the command.

Source

Thrown at clis/gemini/deep-research-result.js:61

    description: 'Export Deep Research report URL from a Gemini conversation',
    domain: GEMINI_DOMAIN,
    strategy: Strategy.COOKIE,
    browser: true,
    siteSession: 'persistent',
    navigateBefore: false,
    defaultFormat: 'plain',
    args: [
        { name: 'query', positional: true, required: false, help: 'Conversation title or URL (optional; defaults to latest conversation)' },
        { name: 'match', required: false, default: 'contains', choices: ['contains', 'exact'], help: 'Match mode' },
        { name: 'timeout', type: 'int', required: false, default: 120, help: 'Max seconds to wait for Docs export (default: 120)' },
    ],
    columns: ['response'],
    func: async (page, kwargs) => {
        const query = String(kwargs.query ?? '').trim();
        const matchMode = parseGeminiTitleMatchMode(kwargs.match);
        const timeoutSeconds = kwargs.timeout;
        if (!Number.isInteger(timeoutSeconds) || timeoutSeconds < 1) {
            throw new ArgumentError('--timeout must be a positive integer (seconds)');
        }
        if (!matchMode) {
            return [{ response: 'Invalid match mode. Use contains or exact.' }];
        }
        const state = await getGeminiPageState(page);
        if (state.isSignedIn === false) {
            return [{ response: 'Not signed in to Gemini.' }];
        }
        const conversationUrl = parseGeminiConversationUrl(query);
        if (conversationUrl) {
            await page.goto(conversationUrl, { waitUntil: 'load', settleMs: 2500 });
            await page.wait(1);
            await waitForGeminiTranscript(page);
            return [{ response: await resolveDeepResearchExportResponse(page, timeoutSeconds) }];
        }
        const conversations = await getGeminiConversationList(page);
        const picked = resolveGeminiConversationForQuery(conversations, query, matchMode);
        if (picked?.Url) {

View on GitHub (pinned to 49907e53dc)

Solutions

1. Pass --timeout as a plain positive integer in seconds, e.g. --timeout 30
2. If the value comes from a variable/env var, ensure it is set, numeric, and integer-valued before invoking
3. Remove any unit suffix or decimal portion (convert 90s -> 90, 1.5 -> 2)
4. Check your arg parser is not passing the flag value as a string; coerce with Number() and verify Number.isInteger

Example fix

// before
opencli gemini deep-research-result --query "..." --timeout 30s
// after
opencli gemini deep-research-result --query "..." --timeout 30

function isValidTimeout(t){ return Number.isInteger(t) && t >= 1; }
const timeout = Number(process.env.TIMEOUT);
if (!isValidTimeout(timeout)) throw new Error('--timeout must be a positive integer (seconds)');

function isPositiveInt(v){ return typeof v === 'number' && Number.isInteger(v) && v >= 1; }

try {
  await run(['gemini','deep-research-result','--query',q,'--timeout',String(timeout)]);
} catch (e) {
  if (String(e.message).includes('--timeout must be a positive integer')) {
    console.error('Fix --timeout: pass an integer >= 1 (seconds), no units.');
  } else throw e;
}

When it happens

Trigger: Calling `opencli gemini deep-research-result` with --timeout given as a non-integer (e.g. 2.5), a string (e.g. '30s' or 'abc'), zero, a negative number, or omitted in a way that yields undefined/null.

Common situations: Passing CLI flags with units ('30s', '1m') instead of plain seconds; a wrapper script interpolating an empty or undefined variable into --timeout; copying a fractional default like 1.5 from docs; shell quoting issues turning the value into a string.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

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

Related errors

• --timeout must be a positive integer (seconds)
• --timeout must be a positive integer (seconds)
• --timeout must be a positive integer (seconds)
• --timeout must be an integer from 1 to 180
• archive search sort must be one of ${SORT_OPTIONS.join(', ')

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