{"record":{"id":"0398ef740fa0b410","repo":"jackwener/OpenCLI","slug":"gmail-operation-page","errorCode":null,"errorMessage":"Gmail ${operation} page","messagePattern":"Gmail (.+?) page","errorType":"error_code","errorClass":"TimeoutError","httpStatus":null,"severity":"error","filePath":"clis/gmail/utils.js","lineNumber":286,"sourceCode":"        body: messageBody(record) || null,\n        attachments,\n      });\n    }\n  }\n  return messages;\n}\n\nasync function ensureGmailReady(page, account, operation) {\n  const currentUrl = typeof page.getCurrentUrl === 'function' ? await page.getCurrentUrl() : null;\n  if (!currentUrl?.startsWith(`${GMAIL_ORIGIN}/mail/u/${account}/`)) {\n    await page.goto(`${GMAIL_ORIGIN}/mail/u/${account}/#inbox`);\n  }\n  for (let attempt = 0; attempt < 60; attempt += 1) {\n    const ready = unwrapBrowserResult(await page.evaluate(`() => !!document.querySelector('input[name=\"q\"]')`), `${operation} readiness probe`);\n    if (ready === true) return;\n    await page.sleep(0.5);\n  }\n  throw new TimeoutError(`Gmail ${operation} page`, 30, 'The Gmail search surface did not become ready. Reload Gmail in the browser and retry.');\n}\n\nasync function installGmailCapture(page, account, endpoint, operation) {\n  if (\n    typeof page?.startNetworkCapture !== 'function'\n    || typeof page?.readNetworkCapture !== 'function'\n  ) {\n    throw new CommandExecutionError(`Gmail ${operation} requires browser response interception`);\n  }\n  if (!await page.startNetworkCapture(`/sync/u/${account}/i/${endpoint}`)) {\n    throw new CommandExecutionError(`Gmail ${operation} could not start browser response interception`);\n  }\n  await page.readNetworkCapture();\n}\n\nasync function waitGmailCaptures(page, endpoint, operation, timeoutSeconds = CAPTURE_WAIT_SECONDS) {\n  const deadline = Date.now() + timeoutSeconds * 1000;\n  let bodylessCaptureObserved = false;","sourceCodeStart":268,"sourceCodeEnd":304,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/gmail/utils.js#L268-L304","documentation":"ensureGmailReady polls for up to 60 attempts (0.5s each) waiting for the Gmail search input (input[name=\"q\"]) to appear, then gives up and throws this TimeoutError with a nominal 30s budget. It means the Gmail web UI never rendered its search surface, so operations like queryThreads/listLabels/fetchThread cannot proceed safely. The library throws rather than returning partial or garbage results.","triggerScenarios":"Calling queryThreads, listLabels, or fetchThread when the Gmail page never shows the search box within ~30s: Gmail loaded a login/redirect page, loaded a plain HTML fallback, the browser is hung, or the DOM never hydrated.","commonSituations":"Google session expired and Gmail redirects to accounts.google.com login; Gmail serves the basic HTML view which lacks input[name=\"q\"]; slow network/proxy delays rendering beyond 30s; a CAPTCHA or 'unusual activity' interstitial is shown; wrong account index in the /mail/u/N URL.","solutions":["Open the browser and confirm Gmail is actually logged in and fully loaded; re-authenticate if redirected to a login page","Reload Gmail in the browser and retry the command (the error hint says exactly this)","Ensure Gmail is set to the standard (not basic HTML) view at mail.google.com","Increase the wait budget / run on a faster connection so rendering finishes within 30s","Verify the correct account index (u/0, u/1, ...) matches the logged-in account"],"exampleFix":"// before: CLI fails immediately after fresh browser launch\nawait queryThreads(page, 'label:inbox');\n// after: ensure session + readiness before the call\nawait page.goto('https://mail.google.com/mail/u/0/');\nawait page.waitForSelector('input[name=\"q\"]', { timeout: 60000 });\nawait queryThreads(page, 'label:inbox');","handlingStrategy":"retry","validationCode":"const ready = await page.evaluate('() => !!document.querySelector(\"input[name=q]\")');\nif (!ready) throw new Error('Run your browser, log into Gmail, and load the standard view first');","typeGuard":null,"tryCatchPattern":"import { TimeoutError } from '<lib>';\ntry {\n  await queryThreads(page, 'in:unread');\n} catch (e) {\n  if (e instanceof TimeoutError && /Gmail .* page/.test(e.message)) {\n    await page.reload();\n    await retry(queryThreads, [page, 'in:unread'], { retries: 2, backoffMs: 3000 });\n  } else throw e;\n}","preventionTips":["Keep the Gmail session logged in and on the standard (non-HTML) view","Reload Gmail and let it fully render before running commands","Use a low-latency connection or raise the wait budget for slow networks","Watch for login redirects/CAPTCHAs before automating"],"tags":["timeout","browser-automation","gmail","page-load"],"backgroundTag":"page-load-timeout","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}