Docs
Troubleshooting
Start here every time:
browserzap doctorIt checks the helper registration, the extension id, the launcher and the bridge, and every failed line says what to do. Its output contains no passwords or page content, so it is safe to email to [email protected].
Common problems
| You see | Do this |
|---|---|
| The side panel stays grey or says Not paired yet | Run browserzap setup, then press the reload icon on the BrowserZap card in chrome://extensions. |
| Doctor: a bridge with a different pairing secret holds 127.0.0.1:9334 next release | Another install or an old bridge is in the way: browserzap restart-bridge, then press Reconnect in the side panel. |
| Doctor: Launcher finds Node and the helper fails next release | Node moved (a version switch with fnm, Volta or nvm, or a reinstall): run browserzap setup again. |
| Doctor: Not blocked by Chrome policy fails next release | Your computer is managed. Ask IT to allow the native helper com.browserzap.bridge and the BrowserZap extension. |
| Your agent does not list BrowserZap's tools | Restart the agent app after setup. To add it by hand, browserzap --help prints the exact configuration. |
| "Update needed" or a version mismatch in the side panel | The extension and the helper are from different versions: npm install -g browserzap@latest, browserzap setup, then reload the extension. |
| Chrome says Disable developer mode extensions | Expected while the extension is loaded unpacked: choose Keep. The Web Store version will not show it. |
| A bar says "BrowserZap" started debugging this browser | Expected while an agent can act; it goes away when the agent ends or after a minute idle. Press Stop to end control. |
| A step stops with "needs you" | The page asked for a password, a code or an approval. Do it on the page or in the side panel; the agent continues. |
A step fails as TARGET_NOT_FOUND on a slow site | Read likelyCause: server_slow or still_rendering means allow more time (timeoutMs, up to 120000). |
| A click in a background tab does nothing on one site | Some sites accept only real clicks; bring the tab to the front. |
What a failed step tells you
| likelyCause | Meaning |
|---|---|
server_slow | The site's server has not answered (the request is named) |
downloading | The page is still loading |
still_rendering | The page shows a spinner or "Loading…" |
page_busy | The page did not respond (heavy script) |
server_error | The site answered with an HTTP error |
site_error | The site showed its own error page |
not_on_page | Nothing is loading and the element is not there |
Logs
Every tool call is recorded in a session log in BrowserZap's folder for 14 days: what it acted on (by name), the outcome and timing. It never contains what you typed or page text.
Start over
browserzap uninstall --purge # removes the helper and all BrowserZap data
npm install -g browserzap
browserzap setup