Troubleshooting

Troubleshooting

Start with browserforge doctor (needs the program running), the Dashboard, or the tools system_status / system_diagnostics.

Symptom	Likely cause and fix
Popup dot is red, "Cannot reach server"	The program is not running or the port differs. curl http://127.0.0.1:7345/health should answer {"ok":true,...}. Start it with browserforge serve.
"Server rejected the token"	You pasted the MCP token instead of the extension token. Run browserforge tokens.
NOT_CONNECTED	Browser closed or extension not connected. It reconnects on its own; open the popup and press Connect.
Multiple browsers are connected; pass browserId	Firefox and Chrome are both connected; pass browserId from system_status on the first call.
STALE_REF	The page changed. Call browser_get_interactive_elements again and use the new refs.
An action hangs / APPROVAL_DENIED	It is waiting for you: open the popup (the badge shows a number) and Approve or Deny.
STOPPED	You pressed STOP. Press Resume in the popup.
Agent cannot connect	Wrong token (use the MCP token), wrong port, or the program is not running. A 403 means the request carried an Origin header or a non-loopback Host.
PATH_NOT_ALLOWED	The file is outside the allowed folders: use ~/.config/browserforge/files (Windows: %APPDATA%\browserforge\files), ~/Documents, ~/Downloads, or start with --allow-dir.
Port already in use	Another copy is running, or pick --port and update the extension URL and the agent configuration.
Windows: "Windows protected your PC"	The installer is not signed yet: More info, then Run anyway.
Windows: plugin that runs a program fails	Give the program's full path in the plugin settings; .cmd / .bat files cannot be started.

Logs: browserforge logs --tail 100, and browserforge diagnostics prints a report you can paste into a bug report. More: docs/TROUBLESHOOTING.md · open an issue.