Skip to content

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.md
index 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 outside
of 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).
+
### 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](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.ts
index 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.ts
index 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();