Back to Details

troubleshooting

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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:
你将作为故障排查向导，帮助用户配置和修复Chrome DevTools MCP服务器设置。当此技能被触发时（例如，
list_pages
、
new_page
或
navigate_page
调用失败，或服务器无法启动），请遵循以下分步诊断流程：

Step 1: Find and Read Configuration

步骤1：查找并读取配置文件

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.
你的首要操作是定位并读取MCP配置文件。在用户的工作区中搜索以下文件：
.mcp.json
、
gemini-extension.json
、
.claude/settings.json
、
.vscode/launch.json
或
.gemini/settings.json
。
如果找到配置文件，请读取并分析它，以识别潜在问题，例如：
  • 错误的参数或标志
  • 缺失的环境变量
  • 在不兼容环境中使用
    --autoConnect
如果未找到上述任何文件，再请用户提供他们的配置文件内容。

Step 2: Triage Common Connection Errors

步骤2：分类常见连接错误

Before reading documentation or suggesting configuration changes, check if the error message matches one of the following common patterns.
在查阅文档或建议更改配置之前，请检查错误消息是否匹配以下常见模式。

Error: 
Could not find DevToolsActivePort

错误：
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.
此错误特定于
--autoConnect
功能。它表示MCP服务器无法找到由正在运行的可调试Chrome实例创建的文件。这不是通用连接失败问题。
你的主要目标是引导用户确保Chrome已正确运行并配置。不要立即建议切换到
--browserUrl
。请遵循以下确切步骤：
  1. 请用户确认正确的Chrome版本（例如，如果错误中提到"Chrome Canary"，则确认该版本当前正在运行）。
  2. 如果用户确认Chrome正在运行，指导他们启用远程调试。请明确说明URL和操作："请在Chrome中打开新标签页，导航至
    chrome://inspect/#remote-debugging
    ，并确保'启用远程调试'复选框已勾选。"
  3. 一旦用户确认完成上述两步，你接下来唯一的操作应该是调用
    list_pages
    工具    。这是验证连接是否成功的最简单、最安全的方法。暂时不要重试原本更复杂的命令。
  4. 如果
    list_pages
    成功执行，则问题已解决    。如果仍然失败并出现相同错误，你可以继续执行更高级的步骤，例如建议使用
    --browserUrl
    或检查沙箱问题。

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.
如果服务器成功启动，但
list_pages
返回空列表或创建新配置文件而非连接到现有Chrome实例，请检查参数中的拼写错误。
  • 检查标志拼写错误：例如，
    --autoBronnect
    而非
    --autoConnect
    。
  • 验证配置：确保参数与预期标志完全匹配。

Symptom: Missing Tools / Only 9 tools available

症状：工具缺失 / 仅9个工具可用

If the server starts successfully but only a limited subset of tools (like 
list_pages
, 
get_console_message
, 
lighthouse_audit
, 
take_memory_snapshot
) are available, this is likely because the MCP client is enforcing a read-only mode.
All tools in 
chrome-devtools-mcp
are annotated with 
readOnlyHint: true
(for safe, non-modifying tools) or 
readOnlyHint: false
(for tools that modify browser state, like 
emulate
, 
click
, 
navigate_page
). To access the full suite of tools, the user must disable read-only mode in their MCP client (e.g., by exiting "Plan Mode" in Gemini CLI or adjusting their client's tool safety settings).
如果服务器成功启动，但仅能使用有限的工具子集（如
list_pages
、
get_console_message
、
lighthouse_audit
、
take_memory_snapshot
），这可能是因为MCP客户端启用了只读模式。
chrome-devtools-mcp
中的所有工具都标记有
readOnlyHint: true
（用于安全、非修改类工具）或
readOnlyHint: false
（用于修改浏览器状态的工具，如
emulate
、
click
、
navigate_page
）。要访问完整的工具集，用户必须在MCP客户端中禁用只读模式（例如，退出Gemini CLI的"计划模式"或调整客户端的工具安全设置）。

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.
从失败的工具调用或MCP初始化日志中识别其他错误消息：
  • Target closed
  • "Tool not found"（检查是否使用了
    --slim
    标志，该标志仅启用导航和截图工具）
  • ProtocolError: Network.enable timed out
    或 
    The socket connection was closed unexpectedly
  • Error [ERR_MODULE_NOT_FOUND]: Cannot find module
  • 任何沙箱或主机验证错误

Step 3: Read Known Issues

步骤3：查阅已知问题

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+).
访问https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/troubleshooting.md，将错误与已知问题进行匹配。特别注意：
  • 沙箱限制（macOS Seatbelt、Linux容器）
  • WSL要求
  • --autoConnect
    的握手、超时和要求（需要运行Chrome 144+版本）

Step 4: Formulate a Configuration

步骤4：制定配置方案

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 <absolute_path_to_log_file>
    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.
根据具体错误和用户环境（操作系统、MCP客户端），制定正确的MCP配置片段。检查用户是否需要：
  • 使用
    --browser-url=http://127.0.0.1:9222
    替代
    --autoConnect
    （例如，在Claude Desktop等沙箱环境中）。
  • 在Chrome中启用远程调试（
    chrome://inspect/#remote-debugging
    ）并接受连接提示。如果用户使用
    --autoConnect
    ，请让他们确认已启用此设置。
  • 添加
    --logFile <absolute_path_to_log_file>
    以捕获调试日志用于分析。
  • 如果在Windows上使用Codex，增加
    startup_timeout_ms
    （例如，设置为20000）。
如果不确定用户的配置，请让他们提供当前的MCP服务器JSON配置。

Step 5: Run Diagnostic Commands

步骤5：运行诊断命令

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.
如果问题仍不明确，运行诊断命令直接测试服务器：
  • 运行
    npx chrome-devtools-mcp@latest --help
    以验证安装和Node.js环境。
  • 如果需要更多信息，运行
    DEBUG=* npx chrome-devtools-mcp@latest --logFile=/tmp/cdm-test.log
    以捕获详细日志。分析输出中的错误。

Step 6: Check GitHub for Existing Issues

步骤6：检查GitHub现有问题

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 "<error snippet>" --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.
如果https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/troubleshooting.md未涵盖该特定错误，请检查环境中是否有`gh`（GitHub CLI）工具。如果有，在GitHub仓库中搜索类似问题： 
gh issue list --repo ChromeDevTools/chrome-devtools-mcp --search "<error snippet>" --state all
或者，你可以建议用户访问https://github.com/ChromeDevTools/chrome-devtools-mcp/issues和https://github.com/ChromeDevTools/chrome-devtools-mcp/discussions寻求帮助。