Chrome DevTools for coding agents
fix: explain launch failures caused by running as root (#2634)
Aleksandr Konovalov9d2922369bfa
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.mdindex de706901..90a6d52c 100644--- a/docs/troubleshooting.md+++ b/docs/troubleshooting.md@@ -81,6 +81,19 @@ 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 outsideof the MCP client sandbox.+### Running as root++Chrome does not start as root+([crbug.com/638180](https://crbug.com/638180)). It exits immediately and+`chrome-devtools-mcp` reports that Chrome failed to start. This is a common+issue in containers and CI images that run everything as root.++Run `chrome-devtools-mcp` as a non-root user. In a container, create an+unprivileged user in the image and switch to it with `USER`; the build itself+can still run as root. For the host-side setup that Chrome's sandbox needs, see+Puppeteer's+[Setting up Chrome Linux sandbox](https://pptr.dev/troubleshooting#setting-up-chrome-linux-sandbox).+### WSLBy 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](https://github.com/microsoft/WSL/issues/14201). Ensure you are using a [Linux distribution compatible with Chrome](https://support.google.com/chrome/a/answer/7100626).diff --git a/src/browser.ts b/src/browser.tsindex 2aec3374..689ac2dd 100644--- a/src/browser.ts+++ b/src/browser.ts@@ -170,6 +170,45 @@ export function detectDisplay(): void {}}+/**+ * Chrome refuses to start as root unless the sandbox is explicitly disabled and+ * only says so on its stderr. Because we launch with `pipe: true`, Puppeteer+ * never surfaces that stderr and the failure reaches the client as an opaque+ * `Protocol error (Target.setDiscoverTargets): Target closed`. Detect the+ * situation and explain the way out instead. See https://crbug.com/638180.+ *+ * Returns `undefined` when the failure cannot be explained by running as root,+ * including on platforms without uids and when the sandbox was already disabled+ * through `--chrome-arg` (in which case root is not what stopped Chrome).+ *+ * Exported for testing.+ */+export function rootSandboxLaunchError(+ error: Error,+ args: readonly string[],+ uid = process.getuid?.(),+): Error | undefined {+ if (uid !== 0) {+ return undefined;+ }+ if (+ args.some(arg => arg === '--no-sandbox' || arg.startsWith('--no-sandbox='))+ ) {+ return undefined;+ }+ return new Error(+ `Chrome failed to start: ${error.message}\n\n` ++ 'chrome-devtools-mcp is running as root and Chrome does not start as root ' ++ '(https://crbug.com/638180). Run chrome-devtools-mcp as a non-root user; in a ' ++ 'container, create an unprivileged user in the image and switch to it with ' ++ "USER. For the setup that Chrome's sandbox needs, see " ++ 'https://pptr.dev/troubleshooting#setting-up-chrome-linux-sandbox.',+ {+ cause: error,+ },+ );+}+export async function launch(options: McpLaunchOptions): Promise<Browser> {const {channel, executablePath, headless, isolated} = options;const profileDirName =@@ -259,6 +298,10 @@ export async function launch(options: McpLaunchOptions): Promise<Browser> {},);}+ const rootError = rootSandboxLaunchError(error as Error, args);+ if (rootError) {+ throw rootError;+ }throw error;}}diff --git a/tests/browser.test.ts b/tests/browser.test.tsindex 191c2ffa..f3ec5f27 100644--- a/tests/browser.test.ts+++ b/tests/browser.test.ts@@ -16,6 +16,7 @@ import {ensureBrowserConnected,launch,makeTargetFilter,+ rootSandboxLaunchError,} from '../src/browser.js';import type {Browser} from '../src/third_party/index.js';@@ -61,6 +62,56 @@ describe('browser', () => {detectDisplay();});+ describe('rootSandboxLaunchError', () => {+ const targetClosed = new Error(+ 'Protocol error (Target.setDiscoverTargets): Target closed',+ );++ it('explains an opaque launch failure when running as root', () => {+ const error = rootSandboxLaunchError(targetClosed, [], 0);+ assert.ok(error);+ assert.match(error.message, /non-root user/);+ assert.match(error.message, /pptr\.dev\/troubleshooting/);+ // The original failure stays visible so unrelated errors are not masked.+ assert.match(error.message, /Target closed/);+ assert.strictEqual(error.cause, targetClosed);+ });++ it('does not explain failures when not running as root', () => {+ assert.strictEqual(+ rootSandboxLaunchError(targetClosed, [], 1000),+ undefined,+ );+ });++ it('does not explain failures on platforms without uids', () => {+ assert.strictEqual(+ rootSandboxLaunchError(targetClosed, [], undefined),+ undefined,+ );+ });++ it('does not explain failures when the sandbox is already disabled', () => {+ assert.strictEqual(+ rootSandboxLaunchError(targetClosed, ['--no-sandbox'], 0),+ undefined,+ );+ assert.strictEqual(+ rootSandboxLaunchError(targetClosed, ['--no-sandbox=true'], 0),+ undefined,+ );+ });++ it('is not fooled by unrelated arguments that start the same', () => {+ assert.ok(+ rootSandboxLaunchError(targetClosed, ['--no-sandbox-and-elevated'], 0),+ );+ assert.ok(+ rootSandboxLaunchError(targetClosed, ['--disable-setuid-sandbox'], 0),+ );+ });+ });+it('cannot launch multiple times with the same profile', async () => {await runWithRetry(async () => {const tmpDir = os.tmpdir();