jackwener/OpenCLI · error · CommandExecutionError

Gmail ${operation} response exceeded the browser capture lim

Error message

Gmail ${operation} response exceeded the browser capture limit

What it means

This CommandExecutionError is thrown by parseJsonCapture when the browser-bridge network capture for a Gmail /sync response has responseBodyTruncated === true, meaning the response body exceeded the capture buffer (MAX_BODY_CHARS / bridge capture limit) and was cut off. The library refuses to parse a truncated body because partial JSON would silently drop threads or messages. It is thrown before any parsing is attempted.

Source

Thrown at clis/gmail/utils.js:100

    .replace(/<br\s*\/?\s*>/gi, '\n')
    .replace(/<\/(p|div|li|tr|h[1-6])>/gi, '\n')
    .replace(/<[^>]+>/g, ' '))
    .replace(/[ \t]+/g, ' ')
    .replace(/ *\n */g, '\n')
    .replace(/\n{3,}/g, '\n\n')
    .trim();
}

function parseJsonCapture(entry, operation) {
  const status = Number(entry?.responseStatus || 0);
  if (status === 401 || status === 403) {
    throw new AuthRequiredError(GMAIL_HOST, `Gmail ${operation} returned HTTP ${status}`);
  }
  if (status !== 200) {
    throw new CommandExecutionError(`Gmail ${operation} returned HTTP ${status || 'unknown'}`);
  }
  if (entry?.responseBodyTruncated === true) {
    throw new CommandExecutionError(`Gmail ${operation} response exceeded the browser capture limit`);
  }
  const body = entry?.responsePreview;
  if (Array.isArray(body)) return body;
  if (typeof body !== 'string') {
    throw new CommandExecutionError(`Gmail ${operation} response body was unavailable`);
  }
  try {
    const parsed = JSON.parse(body.replace(/^\)\]\}'\s*/, ''));
    if (!Array.isArray(parsed)) throw new Error('not an array');
    return parsed;
  } catch {
    throw new CommandExecutionError(`Gmail ${operation} returned malformed JSON`);
  }
}

function addressRef(value) {
  if (!Array.isArray(value)) return null;
  const address = cleanString(value[1]);

View on GitHub (pinned to 49907e53dc)

Solutions

Reduce the requested limit (e.g. --limit 20 instead of 200) and paginate instead of pulling one huge page.
Narrow the search query (add is:unread, after:, label:, or sender filters) so each response page is smaller.
Retry the operation; on a fresh page load Gmail may return a smaller/simpler response.
Update the browser bridge / opencli to a version with a larger capture buffer (MAX_BODY_CHARS).

Example fix

// before
await queryThreads(page, 'in:anywhere', { account: 0, limit: 200 });
// after
await queryThreads(page, 'in:anywhere newer_than:30d', { account: 0, limit: 50 }); // paginate instead

Defensive patterns

Strategy: retry

Validate before calling

// keep the requested page small before calling
const limit = Math.min(userLimit, 50);
if (!/\b(is:|after:|before:|label:|from:)/.test(query) && limit > 50) {
  throw new Error('Broad query with large limit will overflow the capture buffer; narrow the query or lower the limit');
}

Type guard

function isCompleteCapture(entry) {
  return Boolean(entry) && entry.responseBodyTruncated !== true
    && (typeof entry.responsePreview === 'string' || Array.isArray(entry.responsePreview));
}

Try / catch

try {
  threads = await queryThreads(page, query, { limit });
} catch (error) {
  if (error instanceof CommandExecutionError && String(error.message).includes('capture limit')) {
    threads = await queryThreads(page, query, { limit: Math.ceil(limit / 4) }); // retry with smaller pages
  } else throw error;
}

Prevention

Keep per-call limits modest (<=50) and paginate instead of pulling 200 threads at once.
Always constrain broad queries (in:anywhere) with date or label filters.
Run an up-to-date browser bridge with the largest capture buffer.
Watch for this error right after increasing limit — it is a size signal, not a bug.

When it happens

Trigger: waitGmailCaptures receives a capture entry for /i/bv or /i/fd whose body was truncated by the bridge; typically a query returning a very large page (limit near MAX_LIMIT=200, huge threads, wide search like in:anywhere) so the /sync/u/<account>/i/bv or /i/fd response exceeds the capture limit.

Common situations: Listing or searching large mailboxes (hundreds of threads per page), fetching threads with very long HTML bodies or many attachments, low bridge capture-size configuration, older bridge versions with smaller capture buffers.

Related errors

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