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
`scoop install webrain` → Hash check failed!	The download is fine; the bucket entry was mistyped (v0.14.0’s x86_64 hash). `scoop update; scoop cache rm webrain; scoop install webrain --force`. From v0.14.5 the release workflow derives the hash with `sha256sum` from the artifact it just built
`pdf_render requires --features pdfium`	The binary you are running was built without the feature (a `cargo install webrain` build, or anything older than 0.16.2). Run `webrain install pdfium` first — the library is bound at runtime — and if the error persists the build itself lacks the feature: `cargo build --release --features pdfium`. musl builds cannot load the glibc pdfium at all; use `op=extract` / `op=images` there
`webrain: unknown command: serp` — newer subcommands missing	An older manual install shadows the package-managed one. `Get-Command webrain` (PowerShell) / `which -a webrain`, delete the stale copy, reopen the shell
Page renders then “keeps loading”: title right, `challenge: null`, submit stays `disabled`, body stuck at the SSR empty state	Hydration, not a block. Re-probe after ~1s (navigate returns pre-mount), test `Object.keys(el).filter(k=>k.startsWith('__react')).length`, and if a hand-opened tab works set `WEBRAIN_STEALTH_NOISE=0` for the process owning the CDP connection + open a fresh tab (init scripts are per-target)

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).