troubleshooting.md

Troubleshooting

General tips

• Run npx chrome-devtools-mcp@latest --help to test if the MCP server runs on your machine.
• Make sure that your MCP client uses the same npm and node version as your terminal.
• When configuring your MCP client, try using the --yes argument to npx to 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.

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

Using .mcp.json to debug while using a client:

{
  "mcpServers": {
    "chrome-devtools": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "chrome-devtools-mcp@latest",
        "--log-file",
        "/path/to/chrome-devtools-mcp.log"
      ],
      "env": {
        "DEBUG": "*"
      }
    }
  }
}

Specific problems

Codex: error: unexpected argument 'add' found

Some older Codex CLI versions don't include the codex mcp add/list subcommands.

• Run codex mcp --help and check whether it shows add.
• If it does not, upgrade Codex, or add the server manually by editing ~/.codex/config.toml:

[mcp_servers.chrome-devtools]
command = "npx"
args = ["-y", "chrome-devtools-mcp@latest"]

Error [ERR_MODULE_NOT_FOUND]: Cannot find module ...

This usually indicates either a non-supported Node version is in use or that the npm/npx cache is corrupted. Try clearing the cache, uninstalling chrome-devtools-mcp and installing it again. Clear the cache by running:

rm -rf ~/.npm/_npx # NOTE: this might remove other installed npx executables.
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.

Chrome crashes on macOS when using Web Bluetooth

On macOS, Chrome launched by an MCP client application (such as Claude Desktop) may crash when a Web Bluetooth prompt appears. This is caused by a macOS privacy permission violation (TCC).

To resolve this, grant Bluetooth permission to the MCP client application in System Settings > Privacy & Security > Bluetooth. After granting permission, restart the client application and start a new MCP session.

Remote debugging between virtual machine (VM) and host fails

When attempting to connect to Chrome running on a host machine from within a virtual machine (VM), Chrome may reject the connection due to 'Host' header validation. You can bypass this restriction by creating an SSH tunnel from the VM to the host. In the VM, run:

ssh -N -L 127.0.0.1:9222:127.0.0.1:9222 <user>@<host-ip>

Point the MCP connection inside the VM to http://127.0.0.1:9222. This allows DevTools to reach the host browser without triggering the Host validation error.

Connecting to a running Chrome instance (remote debugging, 9222)

If you want chrome-devtools-mcp to attach to an existing Chrome instance, start Chrome with remote debugging enabled, then pass --browserUrl.

1. Start Chrome with a remote debugging port:

   • Linux:

     google-chrome --remote-debugging-port=9222

   • macOS:

     /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222

2. Verify the endpoint is reachable:

   • http://127.0.0.1:9222/json/version should return JSON

3. Start the MCP server and point it at the debugging endpoint:

   npx --yes chrome-devtools-mcp@latest --browserUrl http://127.0.0.1:9222

See also: examples/remote-debugging-9222.mjs.

Operating system sandboxes

Some MCP clients allow sandboxing the MCP server using macOS Seatbelt or Linux containers. If sandboxes are enabled, chrome-devtools-mcp is not able to start Chrome that requires permissions to create its own sandboxes. As a workaround, either disable sandboxing for chrome-devtools-mcp in your MCP client or use --browser-url to connect to a Chrome instance that you start manually outside of the MCP client sandbox.

WSL

By default, chrome-devtools-mcp in WSL requires Chrome to be installed within the Linux environment. While it normally attempts to launch Chrome on the Windows side, this currently fails due to a known WSL issue. Ensure you are using a Linux distribution compatible with Chrome.

Possible workarounds include:

• Install Google Chrome in WSL:

  • wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
  • sudo dpkg -i google-chrome-stable_current_amd64.deb

• Use Mirrored networking:

  1. Configure Mirrored networking for WSL.
  2. Start Chrome on the Windows side with: chrome.exe --remote-debugging-port=9222 --user-data-dir=C:\path\to\dir
  3. Start chrome-devtools-mcp with: npx chrome-devtools-mcp --browser-url http://127.0.0.1:9222

• Use Powershell or Git Bash instead of WSL.