From 1d56a35c9c135acd775da03c8d2f742cf8949b05 Mon Sep 17 00:00:00 2001
From: Claude <claudeaceae@icloud.com>
Date: Mon, 22 Dec 2025 14:57:43 -0500
Subject: [PATCH] docs: enhance troubleshooting guide with detailed solutions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Expand "Target closed" error section with 5 common causes and solutions
- Add new section for configuration file issues with JSON validation tips
- Improve debugging section with platform-specific examples (Windows/Unix)
- Add details about what debug logs contain
- Include --isolated flag example for profile conflicts
- Add example of valid MCP configuration JSON

These improvements help users:
1. Self-diagnose common connection and startup errors
2. Validate their configuration files correctly
3. Enable debugging on different operating systems
4. Understand what information logs provide

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 docs/troubleshooting.md | 60 +++++++++++++++++++++++++++++++++++++----
 1 file changed, 55 insertions(+), 5 deletions(-)

diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 6a7e36bc9..ea025cdee 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -11,11 +11,24 @@
 
 ## Debugging
 
+When reporting issues or diagnosing problems, enable debug logging to capture detailed information.
+
+### Standalone debugging
+
 Start the MCP server with debugging enabled and a log file:
 
-- `DEBUG=* npx chrome-devtools-mcp@latest --log-file=/path/to/chrome-devtools-mcp.log`
+```sh
+DEBUG=* npx chrome-devtools-mcp@latest --log-file=/path/to/chrome-devtools-mcp.log
+```
+
+On Windows (PowerShell):
+```powershell
+$env:DEBUG="*"; npx chrome-devtools-mcp@latest --log-file=C:\path\to\chrome-devtools-mcp.log
+```
+
+### Debugging with an MCP client
 
-Using `.mcp.json` to debug while using a client:
+Configure your MCP client to enable debug logging:
 
 ```json
 {
@@ -24,6 +37,7 @@ Using `.mcp.json` to debug while using a client:
       "type": "stdio",
       "command": "npx",
       "args": [
+        "-y",
         "chrome-devtools-mcp@latest",
         "--log-file",
         "/path/to/chrome-devtools-mcp.log"
@@ -36,6 +50,12 @@ Using `.mcp.json` to debug while using a client:
 }
 ```
 
+The log file will contain detailed information about:
+- Server startup and initialization
+- Tool invocations and parameters
+- Chrome DevTools Protocol (CDP) messages
+- Error stack traces
+
 ## Specific problems
 
 ### `Error [ERR_MODULE_NOT_FOUND]: Cannot find module ...`
@@ -51,9 +71,39 @@ npm cache clean --force
 
 ### `Target closed` error
 
-This indicates that the browser could not be started. Make sure that no Chrome
-instances are running or close them. Make sure you have the latest stable Chrome
-installed and that [your system is able to run Chrome](https://support.google.com/chrome/a/answer/7100626?hl=en).
+This indicates that the browser could not be started or the connection was lost. Common causes and solutions:
+
+1. **Chrome already running**: Close all Chrome instances and try again
+2. **Chrome not installed**: Make sure you have the latest stable Chrome installed
+3. **System requirements**: Verify [your system is able to run Chrome](https://support.google.com/chrome/a/answer/7100626?hl=en)
+4. **Port conflict**: If using `--browser-url`, ensure the debugging port (e.g., 9222) is not already in use
+5. **User data directory locked**: Try using `--isolated` flag to create a temporary profile
+
+Example with isolated mode:
+```sh
+npx -y chrome-devtools-mcp@latest --isolated
+```
+
+### Configuration file not being recognized
+
+If your MCP client is not loading the chrome-devtools-mcp server, check:
+
+1. **File location**: Ensure the configuration file is in the correct location for your MCP client
+2. **JSON syntax**: Validate your JSON using a linter or online validator
+3. **Quotes**: Use double quotes for all JSON strings, not single quotes
+4. **Trailing commas**: Remove any trailing commas in JSON objects or arrays
+
+Example of valid configuration:
+```json
+{
+  "mcpServers": {
+    "chrome-devtools": {
+      "command": "npx",
+      "args": ["-y", "chrome-devtools-mcp@latest"]
+    }
+  }
+}
+```
 
 ### Remote debugging between virtual machine (VM) and host fails