{"record":{"id":"f03e2d7c71526336","repo":"jackwener/OpenCLI","slug":"browser-session-required-for-gmail-labels","errorCode":null,"errorMessage":"Browser session required for gmail labels","messagePattern":"Browser session required for gmail labels","errorType":"error_code","errorClass":"CommandExecutionError","httpStatus":null,"severity":"error","filePath":"clis/gmail/labels.js","lineNumber":20,"sourceCode":"import { cli, Strategy } from '@jackwener/opencli/registry';\nimport { listLabels, parseAccount } from './utils.js';\n\ncli({\n  site: 'gmail',\n  name: 'labels',\n  access: 'read',\n  description: 'List Gmail system and user labels with counts',\n  domain: 'mail.google.com',\n  strategy: Strategy.INTERCEPT,\n  browser: true,\n  navigateBefore: false,\n  siteSession: 'persistent',\n  args: [\n    { name: 'account', type: 'int', default: 0, help: 'Gmail account index from the /mail/u/<index>/ URL' },\n  ],\n  columns: ['id', 'name', 'type', 'unreadCount', 'totalCount'],\n  func: async (page, kwargs) => {\n    if (!page) throw new CommandExecutionError('Browser session required for gmail labels');\n    return listLabels(page, parseAccount(kwargs.account));\n  },\n});\n","sourceCodeStart":2,"sourceCodeEnd":24,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/gmail/labels.js#L2-L24","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nawait run('gmail-labels', {}); // no session attached\n// after\nconst session = await ensurePersistentSession('gmail');\nawait run('gmail-labels', {}, { page: session.page });","handlingStrategy":"validation","validationCode":"if (!page || page.isClosed?.()) {\n  throw new Error('gmail labels needs an open browser page — attach the persistent gmail session');\n}","typeGuard":"function isUsablePage(p) {\n  return !!p && typeof p.evaluate === 'function' && !(typeof p.isClosed === 'function' && p.isClosed());\n}","tryCatchPattern":"try {\n  const labels = await runGmailLabels();\n} catch (e) {\n  if (/Browser session required/.test(e.message)) {\n    const s = await ensurePersistentSession('gmail');\n    return runGmailLabels({ page: s.page });\n  }\n  throw e;\n}","preventionTips":["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"],"tags":["browser","session","gmail","precondition"],"backgroundTag":"browser-session-required","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}