jackwener/OpenCLI · error · CommandExecutionError

Browser session required for gmail ${command}

Error message

Browser session required for gmail ${command}

What it means

The Gmail CLI commands operate by driving a logged-in browser session through a Browser Bridge page object. requirePage is a guard helper: before any thread-query command runs, it verifies a live page was supplied. If the page is null/undefined, the command cannot reach Gmail, so it throws CommandExecutionError instead of failing deep inside browser automation.

Source

Thrown at clis/gmail/search.js:11

import { CommandExecutionError } from '@jackwener/opencli/errors';
import { cli, Strategy } from '@jackwener/opencli/registry';
import { parseAccount, parseLimit, queryThreads } from './utils.js';

const THREAD_COLUMNS = [
  'threadId', 'subject', 'from', 'fromName', 'snippet', 'messageCount',
  'unread', 'starred', 'date', 'labels',
];

function requirePage(page, command) {
  if (!page) throw new CommandExecutionError(`Browser session required for gmail ${command}`);
  return page;
}

const commonArgs = [
  { name: 'limit', type: 'int', default: 20, help: 'Maximum threads to return (1-200)' },
  { name: 'account', type: 'int', default: 0, help: 'Gmail account index from the /mail/u/<index>/ URL' },
];

function registerThreadQuery(name, description, query) {
  cli({
    site: 'gmail',
    name,
    access: 'read',
    description,
    domain: 'mail.google.com',
    strategy: Strategy.INTERCEPT,
    browser: true,
    navigateBefore: false,

View on GitHub (pinned to 49907e53dc)

Solutions

1. Start a browser session (open/connect the Browser Bridge page) before invoking any gmail command.
2. Check that the previous session wasn't closed or crashed; re-run login/launch flow if the browser died.
3. If calling the command programmatically, pass the actual page object returned by the session bootstrap rather than undefined/null.
4. Wrap the call in a handler that detects this error and prompts the user to authenticate/launch the browser first.

Example fix

// before
await runCommand('gmail search', { query: 'from:boss' }); // page is null

// after
const page = await startBrowserSession(); // ensure session first
await runCommand('gmail search', { query: 'from:boss' }, page);

if (!page || typeof page.goto !== 'function') {
  throw new Error('Start a browser session before running gmail commands');
}

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

try {
  await gmailSearch(args);
} catch (e) {
  if (/Browser session required/.test(e.message)) {
    await startBrowserSession();
    return gmailSearch(args);
  }
  throw e;
}

When it happens

Trigger: Calling any registered gmail thread query (via registerThreadQuery) without first establishing a browser session, e.g. invoking the command handler with page=null because no browser was started, the session was closed, or the CLI was run in a non-interactive context that skipped session setup.

Common situations: Running the gmail search command before launching/connecting the browser; a browser crash or user-closed window leaving page null; scripts that call the command function directly (unit tests, automation) bypassing the normal session bootstrap; expired sessions where reconnect logic silently failed.

Related errors

• Browser session required for gmail thread
• 12306 whoami failed: ${probe.detail}
• Browser session required for bilibili comment
• Browser session required for bilibili comments
• Browser session required for bilibili subtitle

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