Troubleshooting

Start every session with webrain doctor — it checks engines, MCP server, CDP ports (9222/9224/9225), and vault. Exit 0 healthy, 2 broken.

The big three

1. Read challenge on every webrain_navigate. Obscura/lightpanda cannot pass interactive challenges — only real Chrome with a persistent profile + session (native login).

2. Obscura v0.2.0+ render builds can screenshot + PDF (no-render builds and lightpanda have no paint engine). Interactive Material / Google widgets and interactive challenges still need real Chrome via cdp_urls:["http://127.0.0.1:9222"].

3. Lightpanda’s screenshot is fake. captureScreenshot returns a placeholder PNG — silently wrong, not an error. And webrain_batch runs sequentially on it (single browser context).

Symptoms → fixes

Symptom	Fix
”shared library” errors running Chrome (Linux)	Install the missing system libs (see Installation)
`challenge: cloudflare_challenge` / `blocked`	`webrain launch <service> <profile> <url>` then `webrain login <service> <profile>`, or re-attach an authenticated Chrome via `CDP_URL=http://127.0.0.1:9222`
Chrome won’t launch / port busy	`webrain doctor`; check `port_blocklist.ps1` on Windows
Batch returns nothing on lightpanda	Expected — single context. Use obscura for parallelism
Google Flights / Material controls don’t open	Real Chrome only, never obscura/lightpanda
Wrong prices on Google Flights	Read from result cards (`li.pIav2d`), never bare `$` text nodes (spurious price grid)
Auth lost after batch	`webrain_setcookies` then `webrain_batch` WITHOUT `cdp_urls` (obscura isolates per-connection cookie jars)
Session cookies gone	They die on Chrome restart — export on the live authenticated browser
`webrain_eval` returns null on obscura	Obscura doesn’t reliably await async JS — use `webrain_batch(op=interact)` for async work
`webrain_batch` errors fast (5s)	No browser backend running — start one or pass `cdp_urls`
LLM getting huge HTML blobs	Stop calling `webrain_observe` what=html — use what=state/clean/eval/extractors

Rules of thumb

Logs go to stderr; MCP speaks JSON on stdout — never redirect stderr into the stream.
webrain_eval doesn’t reliably await async JS on obscura (returns null) — use webrain_batch(op=interact, ...) for async work.
webrain_scrape needs NO browser (pure HTTP, 10–100× faster for static pages).
Material widgets are combobox/option/radio, not button — check the ARIA cheat-sheet in observe (what=a11y).