Troubleshooting: the real bugs

First: is it actually installed?

One exchange tells you more than any amount of config-reading:

You:     Open example.com and take a screenshot.

Claude:  [browser_navigate, then browser_screenshot]
         <image>

An image back - you are running; whatever you are chasing is a specific problem below, not a broken install.

"I don't have browser access" - the client never loaded the server. Restart the client, then check the config file for your client on its install page.

The call hangs, then times out - the server is registered but the extension is not answering. That is the "not connected" section below.

The agent keeps pulling a tab in front of me

Symptom: you are working, and Chrome keeps bringing a tab and its window to the front while the agent runs.

Cause. Chrome does not deliver mouse and keyboard events to a tab that is not the visible one in its window. In a tab you are not looking at, the agent can navigate, read, screenshot, run scripts, click, and fill a field it finds by CSS selector. Key presses, hover, double-click, right-click, coordinate clicks, combobox typing and filling a field found by its text all fail. Since 1.29.2 those tools measure whether the page actually received the event instead of trusting Chrome's acknowledgement, so you get an honest failure rather than a silent one. Up to 1.30.1 the agent then called browser_switch_tab, which brought Chrome in front of you every time, and a screenshot of a covered window raised Chrome and left it there.

What changed in 1.30.2. browser_switch_tab and browser_screenshot no longer bring Chrome in front of you unless the agent asks for it with bring_to_front: true, which the tools tell it to use only after asking you. (browser_navigate with new_tab: true, eget_vindue: true, fokuser: true can also ask for focus for a window of its own; that too is only when the agent passes it.) browser_switch_tab makes the agent's tab active in its window and says whether the page is hidden. If you work in the same Chrome window as the agent, its tab can still become the visible one there; browser_navigate with new_tab: true and eget_vindue: true gives the agent a window of its own (without a position it can still open on your screen, behind or beside what you are doing). A screenshot of a covered window answers window-covered.

What you can do today. Reading, screenshots and scripts work in a background tab or window. Input - typing, hover, coordinate clicks - does not reach a tab that is not the visible one in its window (measured). Whether it reaches the active tab of a window without the operating system's focus is unmeasured in desktop Chrome, so the tools' landed answer decides. When input does not land, the agent has to ask you, and you decide.

Fix status: not fixed, and not fixable by us. 1.30 did not deliver hands-off background input. Some of it cannot be solved at all - CSS :hover is a state the renderer owns and no script can fake it, a script-dispatched event is never isTrusted, and a real double-click's text selection is browser behaviour rather than an event.

Brand-new install: the extension says "not connected" and never turns green

Symptom: you installed the extension (usually from the Chrome Web Store), clicked the toolbar icon, and it sits on "Not connected". Reconnect does nothing. No tool calls work, and your agent says it has no browser access.

Cause: nothing is wrong - you have installed half the product. Browser MCP is a Chrome extension plus a local MCP server, and the extension's only job is to connect to that server. The Chrome Web Store cannot ship the server (it is an npm package your agent runs), and npm cannot ship the extension (Chrome forbids self-installing extensions). So each half is installed separately, and installing only the extension leaves it with nothing to connect to.

Fix - register the missing half with your agent. Claude Code:

claude mcp add --scope user browser-mcp -- npx @agent360/browser-mcp@latest

Codex:

codex mcp add browser-mcp -- npx @agent360/browser-mcp@latest

Cursor, Windsurf or most other clients - add this to that client's MCP config (VS Code uses the root key servers instead of mcpServers):

{"mcpServers": {"browser-mcp": {"command": "npx", "args": ["@agent360/browser-mcp@latest"]}}}

Then restart your agent so it launches the server, and click the extension icon again. Per-client walkthroughs: Claude Code · Cursor · VS Code · Codex.

Note on npx @agent360/browser-mcp install: that command copies the extension files to ~/.browser-mcp/extension/, which is useful for an unpacked install, and registers the server with Claude Code, Codex, VS Code and Cursor if it finds them. Any other client: add the block above to its config.

How to tell this apart from a real fault: if you have never run an npx @agent360/browser-mcp … command on this machine, this is your problem - not the sections below. A quick check that a server is running at all:

lsof -iTCP:9876-9895 -sTCP:LISTEN    # macOS/Linux - expect one line per session using the browser right now

Nothing listed means no server, which means nothing for the extension to find. (The server is not a daemon: it starts when your agent starts and exits when it disconnects, so an empty list while no agent is running is also normal.)

Upload fails with "Not allowed"

Symptom: browser_upload_file or browser_drop_file fails, and the error says "Not allowed".

Cause: Chrome only hands a file to the page when "Allow access to file URLs" is on for the Agent360 Browser MCP extension (chrome://extensions, Agent360 Browser MCP, Details). It is off by default for Chrome Web Store installs, and both tools hand files over the same way.

What you can do: attach the file yourself. The switch also lets the extension open any local file as a page, so turning it on is your call. From 1.30.2 a "Not allowed" error from the handoff is reported as file-access-off unless Chrome confirms that file access is on, and the answer says the same.

"Chrome extension not connected after 5 retries"

Symptom: every tool call fails with this error even though Chrome is open and the extension is installed.

Cause: a stale MCP server process (or its socket) from a previous session - common after a reboot or when several agent sessions have started servers. The extension keeps trying to reach a bridge that is no longer the live one, and after long outages its reconnect loop can give up entirely.

Fix:

1. pkill -f browser-mcp (kills stale servers; your MCP client restarts a fresh one on the next call)
2. If calls still fail: open chrome://extensions and hit the reload icon on Browser MCP - this restarts the extension's service worker and its reconnect loop
3. Retry the tool call

The debugger detaches after 2-3 actions on one tab

Symptom: a sequence of clicks/fills on the same tab works, then actions silently stop landing; browser_navigate and browser_screenshot keep working.

Cause: a Chrome Debugger API attach/detach lifecycle issue in the extension - the attach state can drop after a few debugger-driven actions on one tab. This is our oldest known quirk and the top item on the reliability roadmap.

Workarounds today: batch actions per tab and continue in a new tab when actions stop landing; navigate/screenshot/get_page_content are unaffected. Fix status: a reliability batch (self-recovering attach state, ghost-attach retry, several session-stability fixes) shipped in v1.24.0. It reduces the failure rate but we are not claiming the underlying attach/detach lifecycle is solved - if you still hit it on v1.24.0, please open an issue with the tab and action sequence.

React/Angular forms: filled text appends instead of replacing (macOS)

Symptom: on framework-controlled inputs, browser_fill on a non-empty field produces old-text + new-text.

Cause (we published the audit internally on 2026-07-08 and the diagnosis is embarrassingly specific): the field-clear step sent select-all as Ctrl+A - but on macOS select-all is Cmd+A, so nothing got selected and the new text landed after the old. A second, related gap: fill types per-character instead of using the Input.insertText primitive that our own set_date and set_combobox tools already use, which strict frameworks handle better.

Fix status: shipped in v1.29.1. The Cmd+A clear shipped in v1.24.0 and the typing rewrite in v1.25.0, and we said both halves were fixed. They were not: on 2026-09-08 the append came back on a React form, because the keystroke clear does not empty a controlled field. The fix (read the field back, clear it through the native setter if it is still full) shipped in v1.29.1. (An earlier release note claimed the typing rewrite had already shipped when it had not; we corrected the record rather than let it stand, and then actually shipped it.)

What v1.25.0 changed, and the part we did not expect. The plan was simply to send Input.insertText instead of typing character by character. While doing it we found a second, unrelated defect that was probably the larger cause: the per-character path built the CDP code field as "Key" + character, which is only correct for letters. "1" became Key1, "@" became Key@, a space became Key . Frameworks that branch on event.code - masked inputs, shortcut handlers, several React form libraries - see an unknown code and drop the keystroke. Typing user@example.com was sending two invalid codes, on precisely the characters that make it an email address.

So v1.25.0 does both: fill now sends one Input.insertText, verifies the field is non-empty, and only falls back to character-by-character typing if nothing landed - and that fallback now emits real US-layout key codes (@ reports Digit2, the physical key it sits on). Characters with no sensible mapping (accented, CJK, emoji) omit the field rather than invent one. This also closes a silent failure: a swallowed insert used to return success with an empty field.

Verified on MUI (React-controlled inputs): an email with @ and . lands exactly and floats the Material label - which only happens when React's own state registers the input, not merely the DOM value; a pre-filled field is replaced cleanly with no leftover text; and a 55-character value now produces one input event instead of 55.

execute_script fails on strict-CSP sites

Symptom: raw script execution returns errors (or nothing) on hardened sites - Google properties, Stripe-class dashboards.

Cause: layered content-security-policy restrictions: the isolated-world path is constrained by the extension's own CSP, the main-world path by the site's, and the debugger fallback inherits the detach quirk above.

Workaround (and honestly, the better pattern): use the purpose-built tools - fill, click, set_date, set_combobox, get_page_content run through the debugger/trusted-event layer and work on CSP-strict and React/Angular sites. Reach for execute_script last, not first. A hardened fallback chain shipped in v1.24.0.

Why publish our own bug list?

Because we use Browser MCP all day on real work, the failure modes above are facts of the product today, and a docs page that pretends otherwise costs more trust than it buys. This page changes when the fixes ship - every claim on it is dated.

FAQ

I installed it from the Chrome Web Store. Why do I still have to run a terminal command? Because the store can only give you the extension, and the extension is a bridge - it needs the local MCP server on the other end. That server is the npm package your agent runs, and Google has no way to register it for you. One command, once: claude mcp add --scope user browser-mcp -- npx @agent360/browser-mcp@latest (or the equivalent for your client).

Does the debugger banner ("Agent360 Browser MCP" started debugging this browser) mean something is wrong? No - that is Chrome's standard notice whenever the Debugger API is attached. It disappears when the session ends.

Do these bugs affect what data leaves my machine? No. None of the issues above send anything anywhere. The server and the extension bridge run locally, and what your agent reads goes to your AI client (and, if that client uses a cloud model, on to its model provider), as always.

Where do I report something not listed here? Open a bug report - the template takes two minutes, and dogfooding plus user reports is exactly how the list above got built.