{"record":{"id":"503a1e6ec99fe83c","repo":"jackwener/OpenCLI","slug":"browser-session-required-for-gmail-thread","errorCode":null,"errorMessage":"Browser session required for gmail thread","messagePattern":"Browser session required for gmail thread","errorType":"error_code","errorClass":"CommandExecutionError","httpStatus":null,"severity":"error","filePath":"clis/gmail/thread.js","lineNumber":24,"sourceCode":"  site: 'gmail',\n  name: 'thread',\n  access: 'read',\n  description: 'Read every message in a Gmail thread',\n  domain: 'mail.google.com',\n  strategy: Strategy.INTERCEPT,\n  browser: true,\n  navigateBefore: false,\n  siteSession: 'persistent',\n  args: [\n    { name: 'thread', type: 'string', positional: true, required: true, help: 'Thread id from gmail search, legacy id, or Gmail thread URL' },\n    { name: 'account', type: 'int', default: 0, help: 'Gmail account index from the /mail/u/<index>/ URL' },\n  ],\n  columns: [\n    'messageId', 'legacyMessageId', 'threadId', 'subject', 'from', 'fromName',\n    'to', 'cc', 'date', 'snippet', 'body', 'attachments',\n  ],\n  func: async (page, kwargs) => {\n    if (!page) throw new CommandExecutionError('Browser session required for gmail thread');\n    return fetchThread(page, kwargs.thread, parseAccount(kwargs.account));\n  },\n});\n","sourceCodeStart":6,"sourceCodeEnd":28,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/gmail/thread.js#L6-L28","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nconst result = await gmailThreadCommand(null, { thread: 'abc123', account: 0 });\n\n// after\nconst page = await ensureSession();\nconst result = await gmailThreadCommand(page, { thread: 'abc123', account: 0 });","handlingStrategy":"validation","validationCode":"if (!page) {\n  throw new Error('gmail thread requires an active browser session; call ensureSession() first');\n}","typeGuard":"function hasBrowserPage(p) {\n  return !!p && typeof p === 'object' && typeof p.goto === 'function';\n}","tryCatchPattern":"try {\n  const thread = await gmailThread(page, { thread: id });\n} catch (e) {\n  if (/Browser session required/.test(e.message)) {\n    page = await ensureSession();\n    return gmailThread(page, { thread: id });\n  }\n  throw e;\n}","preventionTips":["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."],"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"}