From 3a025280f79713efd79b174134e27c78f9d16d21 Mon Sep 17 00:00:00 2001 From: Alex Rudenko Date: Tue, 30 Sep 2025 20:31:36 +0200 Subject: [PATCH 1/6] docs: add troubleshooting.md --- docs/troubleshooting.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) create mode 100644 docs/troubleshooting.md diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 00000000..d8c68afc --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,24 @@ +# 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 has the same npm and node versions. +- 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 you client is an IDE, logs would be in the Output pane. + +## Specific problems + +### `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, unsintalling +`chrome-devtools-mcp` and installing it again. + +### `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]. From 7312f0b95459f0b573051950874bd65ee7b3d152 Mon Sep 17 00:00:00 2001 From: Alex Rudenko Date: Tue, 30 Sep 2025 20:33:00 +0200 Subject: [PATCH 2/6] Update docs/troubleshooting.md Co-authored-by: Sebastian Benz --- docs/troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index d8c68afc..62a2488b 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -3,7 +3,7 @@ ## 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 has the same npm and node versions. +- 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. From b6fafeb1f6ae7c49dd89d0e66caad4df0e07df2b Mon Sep 17 00:00:00 2001 From: Alex Rudenko Date: Tue, 30 Sep 2025 20:34:27 +0200 Subject: [PATCH 3/6] Update docs/troubleshooting.md Co-authored-by: Sebastian Benz --- docs/troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 62a2488b..dea374e6 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -14,7 +14,7 @@ ### `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, unsintalling +`npm`/`npx` cache is corrupted. Try clearing the cache, uninstalling `chrome-devtools-mcp` and installing it again. ### `Target closed` error From deaa4228dfdb0e503e7fa156c54b2167597c3eee Mon Sep 17 00:00:00 2001 From: Alex Rudenko Date: Tue, 30 Sep 2025 20:34:04 +0200 Subject: [PATCH 4/6] docs: fix link --- docs/troubleshooting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index dea374e6..e95be694 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -21,4 +21,4 @@ This usually indicates either a non-supported Node version is in use or that the 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]. +installed and that [your system is able to run Chrome](https://support.google.com/chrome/a/answer/7100626?hl=en). From c5b8da4b54fde44f8ed908c05900b64281fb238f Mon Sep 17 00:00:00 2001 From: Alex Rudenko Date: Tue, 30 Sep 2025 23:02:20 +0200 Subject: [PATCH 5/6] docs: add troubleshooting to readme --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 998f306a..98ae06cd 100644 --- a/README.md +++ b/README.md @@ -7,6 +7,8 @@ control and inspect a live Chrome browser. It acts as a Model-Context-Protocol (MCP) server, giving your AI coding assistant access to the full power of Chrome DevTools for reliable automation, in-depth debugging, and performance analysis. +## [Tool reference](./docs/tool-reference.md) | [Changelog](./CHANGELOG.md) | [Contributing](./CONTRIBUTING.md) | [Troubleshooting](./docs/troubleshooting.md) + ## Key features - **Get performance insights**: Uses [Chrome From 516bc54047ecf3b3b41a851e5b70c86af05c4628 Mon Sep 17 00:00:00 2001 From: Alex Rudenko Date: Wed, 1 Oct 2025 09:45:49 +0200 Subject: [PATCH 6/6] docs: add suggestions --- README.md | 2 ++ docs/troubleshooting.md | 7 ++++++- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 98ae06cd..b7534751 100644 --- a/README.md +++ b/README.md @@ -200,6 +200,8 @@ Your MCP client should open the browser and record a performance trace. ## Tools +If you run into any issues, checkout our [troubleshooting guide](./docs/troubleshooting.md). + - **Input automation** (7 tools) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index e95be694..302fe560 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -15,7 +15,12 @@ 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. +`chrome-devtools-mcp` and installing it again. Clear the cache by running: + +```sh +rm -rf ~/.npm/_npx # NOTE: this might remove other installed npx executables. +npm cache clean --force +``` ### `Target closed` error