Skip to content

Troubleshooting

Tran Trung Thanh edited this page Nov 16, 2026 · 1 revision

Troubleshooting

Start with npx -y turbo-browser-mcp --doctor. It prints Node, Playwright, Chromium and CDP diagnostics as JSON. Include that output in any bug report.

No browser found

Install Playwright's Chromium:

npx playwright-core install chromium

Or point the server at an existing browser with --executable <path>.

"Allow remote debugging?" prompt in Chrome 144+

When you enable chrome://inspect/#remote-debugging on the default User Data directory, Chrome asks for approval each time a new WebSocket client connects. That blocks unattended runs. The server has two ways around it:

  • Bridge. --bridge (or npm run bridge) starts a background daemon on http://127.0.0.1:9224 that keeps one connection to Chrome open. You click Allow once, and later clients connect without another prompt. The port can be changed with TURBO_BROWSER_BRIDGE_PORT.
  • Dedicated profile. --launch-chrome (or npm run launch-chrome) starts Chrome with --remote-debugging-port=9222 and its own profile at ~/.turbo-browser-mcp/chrome-profile. The README says this shows no confirmation dialog, even on the first connection.

Refs stop working after navigation

Refs such as [e12] come from the latest snapshot. After a navigation or a large page change they no longer match. Take a new snapshot with inspect_compact, or use returnSnapshot: true on the action. A missing ref in an error message lists the 3 nearest current refs.

A submit button does nothing

That is the submit guard. The result has a blockedBy field. If you want the click to go through, pass allowSubmit: true on that call. See Submit Guard and Safety.

Sites that block automated browsers

The server does not bypass bot checks. Use wait_for_human or --open-profile, described in Submit Guard and Safety.

Still stuck

Open an issue with the bug report form, or ask in Discussions.