{"record":{"id":"9ba46361d17e87fe","repo":"jackwener/OpenCLI","slug":"gmail-operation-requires-native-browser-input","errorCode":null,"errorMessage":"Gmail ${operation} requires native browser input","messagePattern":"Gmail (.+?) requires native browser input","errorType":"exception","errorClass":"CommandExecutionError","httpStatus":null,"severity":"error","filePath":"clis/gmail/utils.js","lineNumber":463,"sourceCode":"      ...row,\n      threadId: cleanString(target).replace(/^#/, ''),\n      date: parsedDate && !Number.isNaN(parsedDate.getTime()) ? parsedDate.toISOString() : null,\n      body: cleanString(row.body).slice(0, MAX_BODY_CHARS) || null,\n    };\n  }).map(({ dateText: _dateText, ...row }) => row);\n}\n\nasync function submitSearch(page, query, operation) {\n  const prepared = unwrapBrowserResult(await page.evaluate(`() => {\n    const field = document.querySelector('input[name=\"q\"]');\n    if (!field) return false;\n    field.focus();\n    field.select();\n    return true;\n  }`), `${operation} search preparation`);\n  if (prepared !== true) throw new CommandExecutionError(`Gmail ${operation} could not find the search input`);\n  if (typeof page.nativeType !== 'function') {\n    throw new CommandExecutionError(`Gmail ${operation} requires native browser input`);\n  }\n  await page.nativeType(query);\n  const actual = unwrapBrowserResult(await page.evaluate(`() => document.querySelector('input[name=\"q\"]')?.value || ''`), `${operation} search input verification`);\n  if (actual !== query) throw new CommandExecutionError(`Gmail ${operation} could not set the search query exactly`);\n  if (typeof page.cdp === 'function') {\n    const key = { key: 'Enter', code: 'Enter', windowsVirtualKeyCode: 13, nativeVirtualKeyCode: 13 };\n    await page.cdp('Input.dispatchKeyEvent', { type: 'rawKeyDown', ...key });\n    await page.cdp('Input.dispatchKeyEvent', { type: 'keyUp', ...key });\n  } else if (typeof page.nativeKeyPress === 'function') {\n    await page.nativeKeyPress('Enter');\n  } else {\n    throw new CommandExecutionError(`Gmail ${operation} requires native browser keyboard input`);\n  }\n}\n\nexport async function queryThreads(page, query, { account = 0, limit = DEFAULT_LIMIT } = {}) {\n  const normalizedQuery = cleanString(query);\n  if (!normalizedQuery) throw new ArgumentError('Gmail search query cannot be empty');","sourceCodeStart":445,"sourceCodeEnd":481,"githubUrl":"https://github.com/jackwener/OpenCLI/blob/49907e53dc3ade5c223ff0c4c2c2785687cec4e6/clis/gmail/utils.js#L445-L481","documentation":"submitSearch requires native OS-level keyboard input: if page.nativeType is not a function it throws this CommandExecutionError. Gmail's search box ignores synthetic DOM value injection, so the library only types through the driver's native input path and refuses anything less reliable.","triggerScenarios":"Calling queryThreads/listLabels with a page wrapper lacking nativeType — e.g. a raw Puppeteer Page (which has keyboard.type but not page.nativeType), a minimal shim, or an outdated browser helper.","commonSituations":"Handing the library a page object from a different driver/version than expected; custom page wrappers that implemented evaluate/sleep but not native input; driver upgrades that renamed the native-type helper.","solutions":["Use the library's browser page wrapper that implements nativeType","Add/upgrade the driver bridge so page.nativeType delegates to the underlying native keyboard API (e.g. page.keyboard.type)","Check typeof page.nativeType === 'function' before invoking Gmail search operations","Align versions of the browser helper and this library"],"exampleFix":"// before: raw puppeteer page without nativeType\nconst page = await browser.newPage();\nawait queryThreads(page, 'in:unread');\n// after: adapt the driver's native keyboard into the expected API\npage.nativeType = (text) => page.keyboard.type(text);\nawait queryThreads(page, 'in:unread');","handlingStrategy":"validation","validationCode":"if (typeof page?.nativeType !== 'function') {\n  throw new Error('use the library page wrapper with nativeType support');\n}","typeGuard":"function supportsNativeType(page) {\n  return typeof page?.nativeType === 'function';\n}","tryCatchPattern":"try {\n  await queryThreads(page, 'in:inbox');\n} catch (e) {\n  if (/requires native browser input/.test(e.message)) {\n    console.error('Swap in the library\\'s instrumented page wrapper');\n  } else throw e;\n}","preventionTips":["Obtain page objects only from the library's browser helper","Verify nativeType exists at startup with a capability check","Keep driver bridge versions aligned with the library"],"tags":["browser-automation","api-mismatch","gmail","input"],"backgroundTag":"missing-api-method","analyzedSha":"49907e53dc3ade5c223ff0c4c2c2785687cec4e6","analyzedAt":"2026-08-29T08:14:47.543Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}