Error Troubleshooting Bible: Every Browser Use Failure, Diagnosed and Fixed

Browser Use fails in a small number of predictable ways. After working through hundreds of GitHub Issues and debugging production deployments, a pattern emerges: the same six or seven root causes account for roughly 90% of all reported failures. The rest are edge cases — version mismatches, platform-specific library issues, or genuinely novel bugs. This chapter maps every common failure to its root cause and gives you the exact fix, in order of frequency.

Symptom 1: Agent stuck at Step 1. The LLM call returns successfully — you can see the plan in the logs — but the browser never executes the first action. Root cause in 80% of cases: headless Chrome failing silently on a JS-heavy page (see Chapter 3 for the full explanation). Quick fix: switch to headful mode with Xvfb. If you're already headful, check whether the page is returning a 200 but rendering a blank body — some sites detect headful-but-automated Chrome and serve an empty page instead of a challenge. Solution: apply the stealth config from Chapter 4. Remaining 20%: the LLM output format changed (Browser Use expects a specific JSON action schema) or the model hallucinated an action the browser can't execute. Check the raw LLM response in the debug logs.

Symptom 2: Docker Chrome crash. The container starts, Chrome's process appears in ps aux for a split second, then disappears. No useful error message in the logs — just a non-zero exit code. Root cause in 95% of cases: missing --no-sandbox flag or insufficient shared memory. Docker allocates 64MB to /dev/shm by default; Chromium uses this for inter-process communication and will crash immediately if it's full. Fix: add shm_size: "2gb" to your docker-compose service definition and ensure --no-sandbox --disable-dev-shm-usage --disable-gpu are in your Chrome launch args. The remaining 5%: Chrome and the installed Playwright browser version disagree. Run playwright install --with-deps chromium inside the container to guarantee version alignment.

Symptom 3: Timeout on element. The agent logs show it found the correct element selector, but the interaction times out. Root cause: the page has loaded (DOMContentLoaded fired), but the target element hasn't rendered yet because it's behind a lazy-load boundary, inside an iframe, or rendered by a JavaScript framework that hydrates after initial paint. Quick fix: increase the default timeout from 30s to 60s and add an explicit wait_for_selector before the interaction. If it's an iframe, the agent needs to explicitly switch contexts — Browser Use's vision mode (using the VLM to see the page screenshot) can sometimes detect elements that the DOM-based agent can't access because they're in a cross-origin iframe.

The full chapter contains the complete 20-error reference table with diagnosis steps and verified fixes for: memory leak after 100+ tasks, LLM rate limiting causing silent retry loops, Playwright browser binary not found, WebSocket disconnection mid-task, "browser has disconnected" errors, and 15 more. Each entry includes the exact error message to grep for, the diagnostic commands to run, and the fix — no "try reinstalling" hand-waving.