docs: add troubleshooting.md

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
@@ -198,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).
+
 <!-- BEGIN AUTO GENERATED TOOLS -->
 
 - **Input automation** (7 tools)

docs/troubleshooting.md

@@ -0,0 +1,29 @@
+# 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 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, uninstalling
+`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
+
+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).