jackwener/OpenCLI · error · CommandExecutionError

Browser session required for gmail attachments

Error message

Browser session required for gmail attachments

What it means

The gmail attachments command requires a live browser session because attachments are scraped from the Gmail web UI, but its func received page === null. The CLI throws CommandExecutionError up front instead of failing later inside fetchThread, indicating the command was invoked without a browser context attached.

Source

Thrown at clis/gmail/attachments.js:21

import { fetchThread, parseAccount } from './utils.js';

cli({
  site: 'gmail',
  name: 'attachments',
  access: 'read',
  description: 'List attachment metadata for a Gmail thread',
  domain: 'mail.google.com',
  strategy: Strategy.INTERCEPT,
  browser: true,
  navigateBefore: false,
  siteSession: 'persistent',
  args: [
    { name: 'thread', type: 'string', positional: true, required: true, help: 'Thread id from gmail search, legacy id, or Gmail thread URL' },
    { name: 'account', type: 'int', default: 0, help: 'Gmail account index from the /mail/u/<index>/ URL' },
  ],
  columns: ['messageId', 'attachmentId', 'name', 'mimeType', 'size'],
  func: async (page, kwargs) => {
    if (!page) throw new CommandExecutionError('Browser session required for gmail attachments');
    const messages = await fetchThread(page, kwargs.thread, parseAccount(kwargs.account));
    const rows = messages.flatMap((message) => message.attachments.map((attachment) => ({
      messageId: message.messageId,
      ...attachment,
    })));
    if (rows.length === 0) {
      throw new EmptyResultError('gmail attachments', 'The Gmail thread has no attachments');
    }
    return rows;
  },
});

View on GitHub (pinned to 49907e53dc)

Solutions

  1. Start/attach the browser session (persistent site session for gmail) before running the command
  2. Verify the browser process is running and the page handle is passed to the command
  3. Re-run the command after any browser crash to re-establish the session
  4. Guard callers: check session/page availability before invoking gmail commands

Example fix

// before
await run('gmail-attachments', { thread: threadId }); // page was null
// after
const page = await getOrLaunchBrowserSession('gmail');
if (!page) throw new Error('launch the gmail browser session first');
await run('gmail-attachments', { thread: threadId }, { page });
Defensive patterns

Strategy: validation

Validate before calling

if (!page || typeof page.evaluate !== 'function') {
  throw new Error('gmail attachments needs a live browser page — attach the gmail session first');
}

Type guard

function isLivePage(p) {
  return !!p && typeof p.evaluate === 'function' && typeof p.goto === 'function';
}

Try / catch

try {
  const rows = await runGmailAttachments(threadId);
} catch (e) {
  if (/Browser session required/.test(e.message)) {
    await ensureBrowserSession('gmail');
    return runGmailAttachments(threadId);
  }
  throw e;
}

Prevention

When it happens

Trigger: Calling the gmail attachments command with no active browser session — e.g. running in headless/offline mode, browser not launched, or session registration skipped — so the func's `if (!page)` guard fires.

Common situations: Running the CLI outside the browser-backed environment; browser session crashed or was closed before invoking; forgetting to start/connect the persistent site session for gmail; automation harness passing null as the page handle.

Related errors

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