Browser Connection Troubleshooting

This document lists common failure scenarios and solutions for OpenClacky's browser automation tool.

Architecture Overview

OpenClacky's browser automation chain:

browser tool (Agent) → browser-manager (Clacky Server) → Chrome/Edge (user's host machine)

• On startup, browser-manager uses BrowserDetector to scan browser UserData directories for the DevToolsActivePort file, which contains the WebSocket port and path
• It then verifies the port is reachable via TCP probe before launching the chrome-devtools-mcp daemon
• In WSL: connects directly to the browser on the Windows host (resolves Windows-side UserData paths via wslpath)
• Reuses the user's real browser session (cookies, login state, etc.)

Issue 1: browser-manager Not Running or Exits Immediately

Symptoms

• Agent reports "Chrome/Edge is not running or remote debugging is not enabled"
• Or reports "chrome-devtools-mcp failed to start"

Cause A: Cannot connect to Chrome/Edge CDP port

On startup, browser-manager calls BrowserDetector.detect which scans for DevToolsActivePort files and verifies port reachability. If no usable browser is found, the daemon won't start.

Troubleshooting steps:

1. Run /browser-setup to let AI guide you through browser configuration (it handles debug mode startup automatically)
2. If previously configured but suddenly can't connect, try fully closing the browser and reopening it, then run /browser-setup again
3. Check if another program is occupying port 9222:
   • macOS/Linux: lsof -i :9222
   • WSL: powershell.exe -Command "netstat -ano | findstr :9222"

Cause B: chrome-devtools-mcp executable not found in PATH

browser-manager launches chrome-devtools-mcp through a login shell. If the command is not on PATH, the daemon exits immediately (non-zero exit code).

Troubleshooting steps:

1. Verify installation: which chrome-devtools-mcp or chrome-devtools-mcp --version
2. If the command exists but browser-manager still reports a path error, it means OpenClacky's startup PATH differs from your current shell
3. Restart OpenClacky to reload environment variables: bash kill -USR1 $CLACKY_MASTER_PID
4. After restart, browser-manager will re-spawn and load the latest PATH via login shell

Issue 2: Everything Looks Normal but Calls Time Out

Symptoms

• browser-setup doctor passes all checks
• But actual browser operations report "timed out after Xs"
• Operations succeed intermittently

Cause

After running for a long time, the CDP connection can become unstable (memory leaks, too many tabs, extension conflicts, etc.).

Solution:

1. Restart the browser: Fully close Chrome/Edge (including background processes and system tray icons), then reopen the browser
2. If you have many tabs open (50+), close unnecessary ones to reduce load
3. Temporarily disable browser extensions that might interfere with CDP (ad blockers, dev tool extensions)
4. Retry the operation after restarting — browser-manager will automatically reconnect

Issue 3: Windows WSL Network Connectivity

Symptoms

• OpenClacky inside WSL cannot connect to the browser on the Windows host
• DevToolsActivePort file exists but TCP port probe fails

Background

• WSL1: Shares the Windows network stack — 127.0.0.1 works directly, usually no issues
• WSL2: Uses a separate virtual network (NAT) — by default, WSL2 cannot directly access Windows host's 127.0.0.1 ports

Solution for WSL2 Users

Enable mirrored networking mode to make WSL2 networking behave like WSL1:

1. Create or edit %USERPROFILE%\.wslconfig in your Windows user directory:

[wsl2]
networkingMode=mirrored

1. Shut down WSL in PowerShell:

wsl --shutdown

1. Reopen your WSL terminal
2. Restart OpenClacky: bash kill -USR1 $CLACKY_MASTER_PID
3. Try connecting to the browser again

How to Check if You're on WSL1 or WSL2

Run in PowerShell:

wsl -l -v

The VERSION column shows 1 for WSL1 and 2 for WSL2.

Still Can't Resolve?

1. Run /browser-setup doctor for a full diagnostic report
2. Share the diagnostic report and error messages with us