browser-bridge-troubleshooting

Browser Bridge Troubleshooting

Diagnostic commands

bash ${CLAUDE_PLUGIN_ROOT}/scripts/status.sh
bash ${CLAUDE_PLUGIN_ROOT}/scripts/setup-wizard.sh --check

MCP tools: bridge_status, bridge_logs (limit 50).

Symptom → fix

Auth timeout loop (connected but not authenticated)

Logs show: Extension auth timeout — closing connection

Cause: Token mismatch — extension bundle doesn't match .bridge-token, or empty token in popup storage.

Fix:

1. bash ${CLAUDE_PLUGIN_ROOT}/scripts/setup-token.sh
2. cd ${CLAUDE_PLUGIN_ROOT} && bun run build:extension
3. Reload extension at chrome://extensions
4. Open popup → verify green dot; if red, paste token → Save & reconnect

Bridge unreachable

Cause: MCP not connected (stdio mode starts bridge on connect), or gateway stopped.

Fix:

• Grok: ensure browser-bridge MCP server is enabled in /mcp
• HTTP mode: bash ${CLAUDE_PLUGIN_ROOT}/scripts/start-gateway.sh

Extension not connected

Cause: Extension not loaded, disabled, or wrong folder.

Fix:

1. Confirm unpacked path is ${CLAUDE_PLUGIN_ROOT}/extension/dist (not extension/ source)
2. Rebuild if dist is stale: bun run build:extension
3. Reload extension

MCP tools fail with "extension not connected"

Run full setup: /browser-bridge-setup

Port conflicts

Default ports: bridge 18793, MCP gateway 18794. Override with BROWSER_BRIDGE_PORT / BROWSER_BRIDGE_MCP_PORT.

Debugger banner in Chrome

Expected when agent uses CDP. User can dismiss; automation still works.

Nuclear reset

bash ${CLAUDE_PLUGIN_ROOT}/scripts/setup-token.sh --regenerate
cd ${CLAUDE_PLUGIN_ROOT} && bun run build:extension
bash ${CLAUDE_PLUGIN_ROOT}/scripts/stop-gateway.sh 2>/dev/null || true
# Reload extension in Chrome, reconnect MCP