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

Launch/attach the browser session (persistent for gmail) before invoking the labels command

jackwener/OpenCLI · error · CommandExecutionError

Browser session required for gmail labels

Error message

Browser session required for gmail labels

What it means

The gmail labels command lists labels by scraping the Gmail web UI, so it requires a live browser page; its func receives page === null when no browser session exists and throws this CommandExecutionError immediately. It is a precondition failure, not a Gmail-side problem.

Source

Thrown at clis/gmail/labels.js:20

import { cli, Strategy } from '@jackwener/opencli/registry';
import { listLabels, parseAccount } from './utils.js';

cli({
  site: 'gmail',
  name: 'labels',
  access: 'read',
  description: 'List Gmail system and user labels with counts',
  domain: 'mail.google.com',
  strategy: Strategy.INTERCEPT,
  browser: true,
  navigateBefore: false,
  siteSession: 'persistent',
  args: [
    { name: 'account', type: 'int', default: 0, help: 'Gmail account index from the /mail/u/<index>/ URL' },
  ],
  columns: ['id', 'name', 'type', 'unreadCount', 'totalCount'],
  func: async (page, kwargs) => {
    if (!page) throw new CommandExecutionError('Browser session required for gmail labels');
    return listLabels(page, parseAccount(kwargs.account));
  },
});

View on GitHub (pinned to 49907e53dc)

Solutions

Launch/attach the browser session (persistent for gmail) before invoking the labels command
Confirm the page handle is actually passed into the command invocation
Restart the browser and re-run if a prior crash left the session dead
Pre-check session availability in calling code before issuing gmail commands

Example fix

// before
await run('gmail-labels', {}); // no session attached
// after
const session = await ensurePersistentSession('gmail');
await run('gmail-labels', {}, { page: session.page });

Defensive patterns

Strategy: validation

Validate before calling

if (!page || page.isClosed?.()) {
  throw new Error('gmail labels needs an open browser page — attach the persistent gmail session');
}

Type guard

function isUsablePage(p) {
  return !!p && typeof p.evaluate === 'function' && !(typeof p.isClosed === 'function' && p.isClosed());
}

Try / catch

try {
  const labels = await runGmailLabels();
} catch (e) {
  if (/Browser session required/.test(e.message)) {
    const s = await ensurePersistentSession('gmail');
    return runGmailLabels({ page: s.page });
  }
  throw e;
}

Prevention

Initialize the persistent gmail site session at startup
Check page.isClosed() before each browser-backed command
Serialize browser access across parallel jobs to avoid shared-session kills
Recover the session automatically on crashes, then re-run
Only invoke gmail commands from the browser-enabled environment

When it happens

Trigger: Invoking the gmail labels command without an active browser session — page is null because the browser was never launched, was closed, or the persistent site session wasn't attached.

Common situations: Running the CLI in an environment without the browser runtime; browser session crashed between commands; forgetting to initialize the persistent gmail site session; parallel jobs closing the shared browser while labels command runs.

Related errors

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