Skip to main content

​
The agent says NOT CONNECTED

The extension is not connected or the companion is not running. Firefox and Zen developer sessions do not use an extension, so check the Developer mode entries in browser_status as well.
  1. Ask for browser_status; it prints the port.
  2. Open the dashboard → Settings, check the port matches, click Connect.
  3. If the dashboard says “Reconnecting…”, no companion is listening. A stdio client starts one when it connects; for HTTP-only use start bunx browspark-mcp@latest --http-only.

​
Port already in use

Another companion owns the port and the new one relays to it; that is normal and needs no action. If instead tool calls fail with port 9223 is in use but the companion there did not answer, something else holds the port. Stop it, or start with --port 9224 and set the same port in the dashboard.

​
The agent is looking at the wrong browser

Chrome, Brave, Firefox and Zen can stay connected together. Ask the agent to call browser_status or browser_tabs, then use the target tab’s returned tabId. To open a new tab, pass the intended extension profile’s browserId or the developer browser’s context. Dashboard tab numbers are browser-native IDs and are different from the IDs MCP tools accept. Browser and tab IDs can change after a companion or browser restart. Refresh the list instead of reusing a saved ID. See Using multiple browsers.

​
Browsers alternate between connected and disconnected

An older companion can cause this: releases before 0.5.0 accept only one extension, so Chrome and Brave repeatedly replace each other. The current Chromium extension requires companion 0.5.0 or later; the Firefox extension requires 0.6.0 or later. An incompatible companion now produces an update message and stops automatic retries without clearing your sharing choices. For a source-built extension, register the companion from the same checkout: command bun, argument the absolute path to companion/src/index.ts. Stop the old companion and its relays, then restart your MCP connection. Starting a new version while the old one still owns the port only creates a relay to the old server. After updating, click Reconnect in each dashboard and check the displayed companion version. Copied profiles can share a saved installation ID. The current companion also uses each browser’s session ID, so those profiles stay connected independently. Reload older extensions after updating them.

​
A healthy browser waits while another is unresponsive

Tab refresh currently waits for responses from all connected extensions. An unresponsive profile can therefore delay calls targeting another browser until its request times out. Disconnect the unresponsive profile from its dashboard, or close that browser, and retry.

​
No usable tabs

Share a tab on the intended profile’s Tabs page or switch on Share everything. Browser-internal pages, extension pages and the Web Store cannot be inspected. The agent can open a tab with browser_tabs {action: "new", browserId} using the profile ID from browser_status. For an already running developer browser, choose its context. Launching another browser is only appropriate when you request it or a tool needs a developer capability.

​
The debugging bar

“Browspark started debugging this browser” is Chrome’s own notice. It goes away 30 seconds after the last command unless an inspection session holds the tab. To hide it permanently start the browser with --silent-debugger-extension-api:
Quit the browser first. Developer mode has no bar.

​
Firefox extension will not load or automate

Use Firefox 153+ or a Zen build based on Firefox 153+. Build the current source and load dist/firefox-extension/manifest.json through Load Temporary Add-on in about:debugging. The Chromium manifest will not load in Firefox. The temporary add-on must be loaded again after restarting the browser. Open Browspark’s dashboard and choose Allow website access if shown, then Enable Firefox automation. Share an HTTP or HTTPS tab afterwards. Browser-internal pages, protected add-on sites and local files cannot be automated. If the companion reports a protocol mismatch, register it from the same source checkout as the extension. See Firefox setup and capabilities.

​
Tools missing or the dashboard looks stale

After a dashboard-only rebuild, refresh its tab. After extension background-process changes, reload the extension in every connected profile: chrome://extensions in Chrome, brave://extensions in Brave, or about:debugging in Firefox and Zen. The dashboard shows a banner for a detected version or setting mismatch, but source changes can retain the same version number. Restart the companion after updating its source, and reconnect each dashboard. The Tools catalog should arrive as soon as the extension connects, including with --http-only before any agent initializes. If it stays empty, ensure the process owning the configured port is the updated companion from the same release or checkout; launching another copy while an old one owns the port just relays to it.

​
Graph waits for connection data while connected

Waiting for connection data means the extension is connected but has not received a graph snapshot. Check Settings → Connection graph, then update the extension and the companion that owns the configured port from the same release or checkout. For a source checkout, run bun run build, reload the extension and restart the source companion. Refresh the dashboard tab after rebuilding its UI. The graph can show the companion and browsers with No agents connected; this is expected until an MCP client initializes. Agent nodes appear after that handshake, and lines indicate connections rather than live command traffic. See Graph for canvas controls and connection troubleshooting for replacing an older companion.

​
A tool says it is switched off

Someone disabled it on a dashboard’s Tools page. For a call targeting an extension tab, check that profile’s dashboard. Calls spanning browsers and developer-session calls use the combined disabled list from connected dashboards, so check each one. Enable the tool there; no restart needed.

​
”Needs developer mode”

The operation uses a protocol domain Chrome hides from extensions (heap profiler, target, browser, raw CDP, Lighthouse). The agent may now launch browser_session for ten minutes under the default policy. Everything else continues in your tabs. For Firefox or Zen, an unsupported in Firefox message describes a limitation of the selected extension or BiDi backend. If the extension requests user-script access, enable that permission in its dashboard first. The same 45 tools are registered, but Chrome-specific actions are unavailable. Check Firefox and Zen coverage; use a Chromium developer session when you need raw CDP, Lighthouse or Chrome profiling.

​
Stale ref

The element left the DOM or the page navigated. Snapshot again.

​
Clicks do nothing

  • A dialog is open: browser_status shows it, browser_dialog resolves it.
  • On Chromium, the page may be paused on a breakpoint: devtools_debugger {action: "resume"}.
  • The element may be hidden or zero-size: check with devtools_elements {action: "box"} on Chromium, or inspect getBoundingClientRect() through devtools_evaluate on Firefox and Zen.
  • If the tool reports that foreground interaction is needed, select that tab yourself or turn off Settings → Browser behavior → Work in background in its dashboard, then retry.
  • On recent Chromium builds, synthetic input can stop reaching a background tab after a navigation until the tab is visible again. If clicks silently do nothing right after browser_navigate, activate the tab (or turn off Work in background) and retry.

​
Keyboard shortcuts do not reach the browser

By design. browser_key sends keys to the page. DevTools, tab switching and reload are browser UI; use devtools_* tools and browser_navigate {action: "reload"}.

​
Developer browser cannot find the executable

Pass browserPath to browser_session launch with the matching browser: "chrome", "brave", "firefox" or "zen". Environment defaults are BROWSPARK_CHROME, BROWSPARK_BRAVE, BROWSPARK_FIREFOX and BROWSPARK_ZEN. For example, Chrome on macOS commonly uses /Applications/Google Chrome.app/Contents/MacOS/Google Chrome. Legacy chromePath and firefoxPath options still work.

​
A context is already running in another browser

Running context names are unique across all browser choices. Use different names such as chrome-work and zen-work, or close the existing context before switching it to another browser. Each browser keeps a separate saved profile. See Developer browser.

​
Sandboxed client: module not found or handshake timeout

The client’s sandbox cannot see bunx or the package cache. Use the HTTP URL from Settings, or set the sandbox to Full Access and use full executable paths, or point it at the compiled dist/browspark. See HTTP endpoint.

​
”Another extension has put a frame into this page”

Chromium refuses to attach the debugger to a tab when another extension has injected one of its own frames into it. Password managers (1Password, Bitwarden) do this on login forms, so every tool fails on that page with Cannot access a chrome-extension:// URL of different extension. The browser enforces this; Browspark cannot bypass it. Set the other extension’s site access to on click for that site (or pause it) and retry. Developer mode has no such restriction, but it does not have your logins. Firefox is not affected.