{"record":{"id":"28692a5b2be733ff","repo":"jackwener/OpenCLI","slug":"browser-session-required-for-gmail-command","errorCode":null,"errorMessage":"Browser session required for gmail ${command}","messagePattern":"Browser session required for gmail (.+?)","errorType":"error_code","errorClass":"CommandExecutionError","httpStatus":null,"severity":"error","filePath":"clis/gmail/search.js","lineNumber":11,"sourceCode":"import { CommandExecutionError } from '@jackwener/opencli/errors';\nimport { cli, Strategy } from '@jackwener/opencli/registry';\nimport { parseAccount, parseLimit, queryThreads } from './utils.js';\n\nconst THREAD_COLUMNS = [\n  'threadId', 'subject', 'from', 'fromName', 'snippet', 'messageCount',\n  'unread', 'starred', 'date', 'labels',\n];\n\nfunction requirePage(page, command) {\n  if (!page) throw new CommandExecutionError(`Browser session required for gmail ${command}`);\n  return page;\n}\n\nconst commonArgs = [\n  { name: 'limit', type: 'int', default: 20, help: 'Maximum threads to return (1-200)' },\n  { name: 'account', type: 'int', default: 0, help: 'Gmail account index from the /mail/u/<index>/ URL' },\n];\n\nfunction registerThreadQuery(name, description, query) {\n  cli({\n    site: 'gmail',\n    name,\n    access: 'read',\n    description,\n    domain: 'mail.google.com',\n    strategy: Strategy.INTERCEPT,\n    browser: true,\n    navigateBefore: false,","sourceCodeStart":1,"sourceCodeEnd":29,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/gmail/search.js#L1-L29","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Start a browser session (open/connect the Browser Bridge page) before invoking any gmail command.","Check that the previous session wasn't closed or crashed; re-run login/launch flow if the browser died.","If calling the command programmatically, pass the actual page object returned by the session bootstrap rather than undefined/null.","Wrap the call in a handler that detects this error and prompts the user to authenticate/launch the browser first."],"exampleFix":"// before\nawait runCommand('gmail search', { query: 'from:boss' }); // page is null\n\n// after\nconst page = await startBrowserSession(); // ensure session first\nawait runCommand('gmail search', { query: 'from:boss' }, page);","handlingStrategy":"validation","validationCode":"if (!page || typeof page.goto !== 'function') {\n  throw new Error('Start a browser session before running gmail commands');\n}","typeGuard":"function hasBrowserPage(p) {\n  return !!p && typeof p === 'object' && typeof p.goto === 'function';\n}","tryCatchPattern":"try {\n  await gmailSearch(args);\n} catch (e) {\n  if (/Browser session required/.test(e.message)) {\n    await startBrowserSession();\n    return gmailSearch(args);\n  }\n  throw e;\n}","preventionTips":["Always bootstrap the browser session before any gmail command in scripts.","Wrap session creation in a shared ensureSession() helper and call it at command start.","Handle browser-disconnect events to reset state and force re-launch.","Validate page presence in CI/test harnesses that invoke command handlers directly."],"tags":["browser-session","gmail","missing-session"],"backgroundTag":"missing-browser-session","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}