{"record":{"id":"96c51f0cdb6e822d","repo":"jackwener/OpenCLI","slug":"gmail-batch-view-response-had-an-unexpected-shape","errorCode":null,"errorMessage":"Gmail batch-view response had an unexpected shape","messagePattern":"Gmail batch-view response had an unexpected shape","errorType":"error_code","errorClass":"CommandExecutionError","httpStatus":null,"severity":"error","filePath":"clis/gmail/utils.js","lineNumber":135,"sourceCode":"  if (!Array.isArray(value)) return null;\n  const address = cleanString(value[1]);\n  if (!address.includes('@')) return null;\n  return { address, name: cleanString(value[2]) || null };\n}\n\nfunction senderFromSummary(message) {\n  return addressRef(Array.isArray(message) ? message[1] : null);\n}\n\nfunction labelIdsFromMessages(messages) {\n  return [...new Set((Array.isArray(messages) ? messages : [])\n    .flatMap((message) => Array.isArray(message?.[10]) ? message[10] : [])\n    .filter((label) => typeof label === 'string' && label.startsWith('^')))];\n}\n\nexport function parseBatchView(body) {\n  if (!Array.isArray(body) || body.length !== 19) {\n    throw new CommandExecutionError('Gmail batch-view response had an unexpected shape');\n  }\n  const rows = Array.isArray(body[2]) ? body[2] : [];\n  return rows.map((wrapper, index) => {\n    const record = Array.isArray(wrapper?.[0]) ? wrapper[0] : null;\n    if (!record || record.length < 5) {\n      throw new CommandExecutionError(`Gmail batch-view returned a malformed thread at index ${index}`);\n    }\n    const threadId = cleanString(record[3]).replace(/^#/, '');\n    const messages = Array.isArray(record[4]) ? record[4] : [];\n    const latest = messages.at(-1);\n    const sender = senderFromSummary(latest);\n    if (!threadId) throw new CommandExecutionError(`Gmail batch-view returned a thread without an id at index ${index}`);\n    const labels = labelIdsFromMessages(messages);\n    return {\n      threadId,\n      subject: cleanString(record[0]) || '(no subject)',\n      from: sender?.address || null,\n      fromName: sender?.name || null,","sourceCodeStart":117,"sourceCodeEnd":153,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/gmail/utils.js#L117-L153","documentation":"parseBatchView validates that the Gmail batch-view (/i/bv) payload is an array of exactly 19 elements before extracting thread rows from body[2]. If the captured body is an array of any other length (or not an array), it throws this CommandExecutionError because the batch-view wire format it knows has changed or the wrong response was captured. It signals a structural mismatch, not bad user input.","triggerScenarios":"waitGmailCaptures hands parseBatchView a body that is not an array or whose length !== 19 — e.g. Gmail's batch-view protocol changed, a different /sync response matched the /i/bv filter, or a partial/garbage payload was captured.","commonSituations":"Gmail web-app rollout changing the bv payload shape, capturing a non-list response (e.g. settings or a different sync channel) that shares the /i/bv URL, future Gmail versions.","solutions":["Retry the command; if it persists, capture the raw payload and report it — the parser needs updating for the new shape.","Update opencli to the latest version so parseBatchView matches the current Gmail wire format.","Verify the captured page is the normal Gmail mail view (not settings/offline), then rerun.","Clear Gmail's cache/cookies and reload to rule out stale app bundles serving a different shape."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"null","typeGuard":"function isBatchViewEnvelope(body) {\n  return Array.isArray(body) && body.length === 19 && Array.isArray(body[2]);\n}","tryCatchPattern":"try {\n  threads = await gmailSearch(query);\n} catch (error) {\n  if (String(error.message).includes('unexpected shape')) {\n    reportToVendor('gmail batch-view payload shape changed', error);\n    // fallback: narrow the query and retry once\n    threads = await gmailSearch(query + ' newer_than:90d');\n  } else throw error;\n}","preventionTips":["Pin/update the CLI version alongside Gmail web-app rollouts; shape errors mean the wire format moved.","Don't run other Gmail actions in the same tab during a search capture window.","Treat first occurrence as transient (retry), persistent occurrence as a parser-update requirement.","Keep the browser profile's Gmail app bundle fresh (hard reload) to avoid stale shapes."],"tags":["gmail","schema-validation","response-shape","browser-bridge"],"backgroundTag":"unexpected-response-shape","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}