diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index e9f51c037..83b579b04 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -8,6 +8,7 @@ auto-accept installation prompt. - Find a specific error in the output of the `chrome-devtools-mcp` server. Usually, if your client is an IDE, logs would be in the Output pane. +- Search the [GitHub repository issues and discussions](https://github.com/ChromeDevTools/chrome-devtools-mcp) for help or existing similar problems. ## Debugging @@ -98,3 +99,12 @@ Possible workarounds include: `npx chrome-devtools-mcp --browser-url http://127.0.0.1:9222` - **Use Powershell or Git Bash** instead of WSL. + +### Connection timeouts with `--autoConnect` + +If you are using the `--autoConnect` flag and tools like `list_pages`, `new_page`, or `navigate_page` fail with a timeout (e.g., `ProtocolError: Network.enable timed out` or `The socket connection was closed unexpectedly`), this usually means the MCP server cannot handshake with the running Chrome instance correctly. Ensure: + +1. Chrome 144+ is **already** running. +2. Remote debugging is enabled in Chrome via `chrome://inspect/#remote-debugging`. +3. You have allowed the remote debugging connection prompt in the browser. +4. There is no other MCP server or tool trying to connect to the same debugging port. diff --git a/skills/troubleshooting/SKILL.md b/skills/troubleshooting/SKILL.md new file mode 100644 index 000000000..1c89ecc28 --- /dev/null +++ b/skills/troubleshooting/SKILL.md @@ -0,0 +1,85 @@ +--- +name: troubleshooting +description: Uses Chrome DevTools MCP and documentation to troubleshoot connection and target issues. Trigger this skill when list_pages, new_page, or navigate_page fail, or when the server initialization fails. +--- + +## Troubleshooting Wizard + +You are acting as a troubleshooting wizard to help the user configure and fix their Chrome DevTools MCP server setup. When this skill is triggered (e.g., because `list_pages`, `new_page`, or `navigate_page` failed, or the server wouldn't start), follow this step-by-step diagnostic process: + +### Step 1: Find and Read Configuration + +Your first action should be to locate and read the MCP configuration file. Search for the following files in the user's workspace: `.mcp.json`, `gemini-extension.json`, `.claude/settings.json`, `.vscode/launch.json`, or `.gemini/settings.json`. + +If you find a configuration file, read and interpret it to identify potential issues such as: + +- Incorrect arguments or flags. +- Missing environment variables. +- Usage of `--autoConnect` in incompatible environments. + +If you cannot find any of these files, only then should you ask the user to provide their configuration file content. + +### Step 2: Triage Common Connection Errors + +Before reading documentation or suggesting configuration changes, check if the error message matches one of the following common patterns. + +#### Error: `Could not find DevToolsActivePort` + +This error is highly specific to the `--autoConnect` feature. It means the MCP server cannot find the file created by a running, debuggable Chrome instance. This is not a generic connection failure. + +Your primary goal is to guide the user to ensure Chrome is running and properly configured. Do not immediately suggest switching to `--browserUrl`. Follow this exact sequence: + +1. **Ask the user to confirm that the correct Chrome version** (e.g., "Chrome Canary" if the error mentions it) is currently running. +2. **If the user confirms it is running, instruct them to enable remote debugging.** Be very specific about the URL and the action: "Please open a new tab in Chrome, navigate to `chrome://inspect/#remote-debugging`, and make sure the 'Enable remote debugging' checkbox is checked." +3. **Once the user confirms both steps, your only next action should be to call the `list_pages` tool.** This is the simplest and safest way to verify if the connection is now successful. Do not retry the original, more complex command yet. +4. **If `list_pages` succeeds, the problem is resolved.** If it still fails with the same error, then you can proceed to the more advanced steps like suggesting `--browserUrl` or checking for sandboxing issues. + +#### Symptom: Server starts but creates a new empty profile + +If the server starts successfully but `list_pages` returns an empty list or creates a new profile instead of connecting to the existing Chrome instance, check for typos in the arguments. + +- **Check for flag typos:** For example, `--autoBronnect` instead of `--autoConnect`. +- **Verify the configuration:** Ensure the arguments match the expected flags exactly. + +#### Other Common Errors + +Identify other error messages from the failed tool call or the MCP initialization logs: + +- `Target closed` +- "Tool not found" (check if they are using `--slim` which only enables navigation and screenshot tools). +- `ProtocolError: Network.enable timed out` or `The socket connection was closed unexpectedly` +- `Error [ERR_MODULE_NOT_FOUND]: Cannot find module` +- Any sandboxing or host validation errors. + +### Step 3: Read Known Issues + +Read the contents of https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/troubleshooting.md to map the error to a known issue. Pay close attention to: + +- Sandboxing restrictions (macOS Seatbelt, Linux containers). +- WSL requirements. +- `--autoConnect` handshakes, timeouts, and requirements (requires **running** Chrome 144+). + +### Step 4: Formulate a Configuration + +Based on the exact error and the user's environment (OS, MCP client), formulate the correct MCP configuration snippet. Check if they need to: + +- Pass `--browser-url=http://127.0.0.1:9222` instead of `--autoConnect` (e.g. if they are in a sandboxed environment like Claude Desktop). +- Enable remote debugging in Chrome (`chrome://inspect/#remote-debugging`) and accept the connection prompt. **Ask the user to verify this is enabled if using `--autoConnect`.** +- Add `--logFile ` to capture debug logs for analysis. +- Increase `startup_timeout_ms` (e.g. to 20000) if using Codex on Windows. + +_If you are unsure of the user's configuration, ask the user to provide their current MCP server JSON configuration._ + +### Step 5: Run Diagnostic Commands + +If the issue is still unclear, run diagnostic commands to test the server directly: + +- Run `npx chrome-devtools-mcp@latest --help` to verify the installation and Node.js environment. +- If you need more information, run `DEBUG=* npx chrome-devtools-mcp@latest --logFile=/tmp/cdm-test.log` to capture verbose logs. Analyze the output for errors. + +### Step 6: Check GitHub for Existing Issues + +If https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/troubleshooting.md does not cover the specific error, check if the `gh` (GitHub CLI) tool is available in the environment. If so, search the GitHub repository for similar issues: +`gh issue list --repo ChromeDevTools/chrome-devtools-mcp --search "" --state all` + +Alternatively, you can recommend that the user checks https://github.com/ChromeDevTools/chrome-devtools-mcp/issues and https://github.com/ChromeDevTools/chrome-devtools-mcp/discussions for help.