What causes "Browser session required for gmail thread" in jackwener/OpenCLI?

Establish/restore the browser session before running `gmail thread`.

jackwener/OpenCLI · error · CommandExecutionError

Browser session required for gmail thread

Error message

Browser session required for gmail thread

What it means

The `gmail thread` command requires an active browser session to fetch a full thread from Gmail's web UI. The command's func handler explicitly checks the page argument and throws CommandExecutionError when it is null, because fetchThread cannot operate without a live page.

Source

Thrown at clis/gmail/thread.js:24

  site: 'gmail',
  name: 'thread',
  access: 'read',
  description: 'Read every message in 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', 'legacyMessageId', 'threadId', 'subject', 'from', 'fromName',
    'to', 'cc', 'date', 'snippet', 'body', 'attachments',
  ],
  func: async (page, kwargs) => {
    if (!page) throw new CommandExecutionError('Browser session required for gmail thread');
    return fetchThread(page, kwargs.thread, parseAccount(kwargs.account));
  },
});

View on GitHub (pinned to 49907e53dc)

Solutions

Establish/restore the browser session before running `gmail thread`.
If the browser was closed, relaunch and re-authenticate, then retry the command.
When invoking programmatically, ensure the page object is threaded through to the command func.
Add an up-front session check so the user is told to open the browser before the command executes.

Example fix

// before
const result = await gmailThreadCommand(null, { thread: 'abc123', account: 0 });

// after
const page = await ensureSession();
const result = await gmailThreadCommand(page, { thread: 'abc123', account: 0 });

Defensive patterns

Strategy: validation

Validate before calling

if (!page) {
  throw new Error('gmail thread requires an active browser session; call ensureSession() first');
}

Type guard

function hasBrowserPage(p) {
  return !!p && typeof p === 'object' && typeof p.goto === 'function';
}

Try / catch

try {
  const thread = await gmailThread(page, { thread: id });
} catch (e) {
  if (/Browser session required/.test(e.message)) {
    page = await ensureSession();
    return gmailThread(page, { thread: id });
  }
  throw e;
}

Prevention

Open the browser and confirm you're logged into Gmail before fetching threads.
Keep the session alive between search and thread commands (same process/profile).
Add an up-front page check in wrappers around thread queries.
Log session lifecycle so closed browsers are detected early.

When it happens

Trigger: Invoking the `gmail thread` command with no page object: no browser session was established, the session was closed before the call, or the caller passed kwargs only and omitted/zeroed the page parameter.

Common situations: User runs `gmail thread <id>` in a fresh CLI process without launching the browser; the browser was quit between the search and thread commands; automation scripts calling the command handler directly without a page.

Related errors

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