jackwener/OpenCLI · error · CommandExecutionError

Gmail ${operation} could not set the search query exactly

Error message

Gmail ${operation} could not set the search query exactly

What it means

submitSearch verifies, by re-reading the DOM, that the search input's value exactly equals the requested query; if not it throws this CommandExecutionError. This guards against Gmail silently altering, truncating, or ignoring typed characters (autocorrect, focus loss, IME interference) which would produce wrong search results.

Source

Thrown at clis/gmail/utils.js:467

    };
  }).map(({ dateText: _dateText, ...row }) => row);
}

async function submitSearch(page, query, operation) {
  const prepared = unwrapBrowserResult(await page.evaluate(`() => {
    const field = document.querySelector('input[name="q"]');
    if (!field) return false;
    field.focus();
    field.select();
    return true;
  }`), `${operation} search preparation`);
  if (prepared !== true) throw new CommandExecutionError(`Gmail ${operation} could not find the search input`);
  if (typeof page.nativeType !== 'function') {
    throw new CommandExecutionError(`Gmail ${operation} requires native browser input`);
  }
  await page.nativeType(query);
  const actual = unwrapBrowserResult(await page.evaluate(`() => document.querySelector('input[name="q"]')?.value || ''`), `${operation} search input verification`);
  if (actual !== query) throw new CommandExecutionError(`Gmail ${operation} could not set the search query exactly`);
  if (typeof page.cdp === 'function') {
    const key = { key: 'Enter', code: 'Enter', windowsVirtualKeyCode: 13, nativeVirtualKeyCode: 13 };
    await page.cdp('Input.dispatchKeyEvent', { type: 'rawKeyDown', ...key });
    await page.cdp('Input.dispatchKeyEvent', { type: 'keyUp', ...key });
  } else if (typeof page.nativeKeyPress === 'function') {
    await page.nativeKeyPress('Enter');
  } else {
    throw new CommandExecutionError(`Gmail ${operation} requires native browser keyboard input`);
  }
}

export async function queryThreads(page, query, { account = 0, limit = DEFAULT_LIMIT } = {}) {
  const normalizedQuery = cleanString(query);
  if (!normalizedQuery) throw new ArgumentError('Gmail search query cannot be empty');
  await ensureGmailReady(page, account, 'thread list');
  await installGmailCapture(page, account, 'bv', 'thread list');

  const rows = [];

View on GitHub (pinned to 49907e53dc)

Solutions

  1. Simplify the query (avoid characters Gmail rewrites) and retry
  2. Ensure no dialogs/autocomplete popups steal focus; dismiss them or wait for Gmail to settle before searching
  3. Type the query with a small per-keystroke delay so Gmail's autocomplete doesn't race the input
  4. Verify the query round-trips by reading the input value in your own pre-check
  5. Test whether an IME/keyboard layout is altering input and switch to a plain US layout

Example fix

// before: query rewritten by autocomplete
await queryThreads(page, 'subject:(hello world)');
// after: quote/simplify and retry with settled focus
await page.sleep(1);
await queryThreads(page, 'subject:"hello world"');
Defensive patterns

Strategy: validation

Validate before calling

// pre-check the query survives typing: avoid chars Gmail rewrites
const safe = /^[\w:@<>"{} ]+$/.test(query);
if (!safe) throw new Error('query contains characters Gmail may rewrite; quote or simplify it');

Try / catch

try {
  const threads = await queryThreads(page, rawQuery);
} catch (e) {
  if (/could not set the search query exactly/.test(e.message)) {
    await page.sleep(1); // let autocomplete settle, then retry quoted
    return queryThreads(page, JSON.stringify(rawQuery));
  }
  throw e;
}

Prevention

When it happens

Trigger: page.nativeType(query) ran but document.querySelector('input[name="q"]').value !== query — characters dropped, Gmail reformatted the query (e.g. stripped or auto-completed tokens), or the input lost focus mid-typing.

Common situations: Gmail's search autocomplete rewriting the box while typing; special characters or non-ASCII queries mangled by keyboard layout/IME; focus stolen by a Gmail dialog; very long queries hitting an input limit.

Related errors

AI-assisted analysis of jackwener/OpenCLI@49907e53dc (2026-08-29). Data as JSON: /api/errors/1c9db2945e127ddd. Report an issue: GitHub.