Troubleshooting
Errors arrive as {tool}: {detail} messages — catchable
and retryable. Stack traces and crashes are engine bugs:
report the expression, do not retry blind.
Session errors
| Message | Fix |
|---|---|
no such session (open again — handles die with their browser.) | open again; the browser is gone |
record is unparseable (close the handle and open again.) | close the handle, open fresh |
no free port in 9333-9432 (close something first.) | close --all --yes, retry |
no chromium executable on PATH | Install Chromium or set CHROMIUM_PATH |
browser on <port> never answered /json/version | Headed needs a display (Xvfb or drop --headed); headless means the port is taken or Chromium is too old (floor: 152) |
foreign browser has no page tab to borrow. | Open a page tab in the foreign browser first |
borrowed tab refused navigation: … | The foreign tab blocked the nav — pick another tab or URL |
close needs <handle|--all>, open needs <url> | Pass the missing arg (exit 2, usage) |
<verb> needs --yes (deliberate writes only) | Add --yes to register, unregister, close |
A thin MCP tool surface is usually a stale client snapshot, not a server fault: reconnect the MCP session and the seven tools re-list.
Authoring errors
| Message | Fix |
|---|---|
bad tool name '…' | Match ^[A-Za-z0-9_.-]{1,128}$ |
description is empty / code is empty | Fill the missing field |
inputSchema must be a JSON Schema object | Pass an object schema, not an array or scalar |
(spec rejects, pre-dial). | The spec never reached the page — fix shape and retry |
page refused: … | The page rejected registration — refresh discovery (viewport, variants, hooks) and re-author |
registered but absent from the list — page dropped it, nothing persisted. | The page took then dropped the tool — re-author against fresh discovery |
fixture failed (…) — tool rolled back, nothing persisted. | The body failed its own fixture — fix the body, keep the spec; nothing was saved |
'…' is not session-authored (native or unknown) — refusing | unregister only drops authored tools; native tools stay |
'…' still listed after unregister — page refused silently. | Page kept the tool — record and page disagree, investigate before retrying |
no controller (page navigated or never registered here) | The page navigated away (tools die with navigation) — re-open to re-apply, then retry |
Rot signal in list: staleSuspect means a call
recently failed as page-refused or tool-vanished.
Recovery is re-register against fresh discovery.
Composition errors
| Message | Fix |
|---|---|
pass handle or sessions. | Pass one handle or a sessions[] array |
at most 8 sessions per run: close something first. | Drop to 8 or fewer sessions |
bad timeoutMs: want 1-300000 ms | Pick a timeout in range (default 60000) |
bad maxToolCalls/maxChars/maxResultChars: want an integer ≥ 1 | Fix the named budget |
code is … chars (max 64000): chunk it. | Split the program |
unknown tool path: … | Re-list the session; the path is stale or namespaced wrong |
TimeoutExceeded / ToolCallLimitExceeded | Results so far travel with the diagnostic — narrow scope, raise the budget, rerun |
no such session: <handle> (search with handles) | Drop the dead handle or re-open it |
browser unreachable (search skipped[]) | One session died mid-sweep — the rest still ranked |