Skip to content

Chrome DevTools for coding agents

fix: suggest --headless when Chrome cannot find an X server (#3428)

John Costa8b0856ad3f40
diff --git a/src/BrowserManager.ts b/src/BrowserManager.ts
index 66a1195d..da1f139d 100644
--- a/src/BrowserManager.ts
+++ b/src/BrowserManager.ts
@@ -121,6 +121,31 @@ export class BrowserManager {
);
}
+ /**
+ * Puppeteer reports a headed launch without a display as "Missing X server"
+ * and suggests its own `headless` option, which users of this server cannot
+ * set directly. Point them to the `--headless` flag instead.
+ *
+ * Returns `undefined` for headless launches and for unrelated failures.
+ */
+ static missingDisplayLaunchError(
+ error: Error,
+ headless: boolean,
+ ): Error | undefined {
+ if (headless || !error.message.includes('Missing X server')) {
+ return undefined;
+ }
+ return new Error(
+ `Chrome failed to start: ${error.message}\n\n` +
+ 'No X server is available to show a headed Chrome window. Start ' +
+ 'chrome-devtools-mcp with --headless, set DISPLAY to a running X ' +
+ 'server, or run chrome-devtools-mcp under xvfb-run.',
+ {
+ cause: error,
+ },
+ );
+ }
+
async ensureBrowser(): Promise<Browser> {
if (this.#initPromise) {
return await this.#initPromise;
@@ -334,6 +359,13 @@ export class BrowserManager {
if (rootError) {
throw rootError;
}
+ const displayError = BrowserManager.missingDisplayLaunchError(
+ error,
+ headless,
+ );
+ if (displayError) {
+ throw displayError;
+ }
}
throw error;
}
diff --git a/tests/browser.test.ts b/tests/browser.test.ts
index 03a66e4b..856159d2 100644
--- a/tests/browser.test.ts
+++ b/tests/browser.test.ts
@@ -753,6 +753,43 @@ describe('browser', () => {
});
});
+ describe('missingDisplayLaunchError', () => {
+ const missingXServer = new Error(
+ 'Missing X server to start the headful browser. Either set headless ' +
+ 'to true or use xvfb-run to run your Puppeteer script.',
+ );
+
+ it('names --headless when a headed launch has no X server', () => {
+ const error = BrowserManager.missingDisplayLaunchError(
+ missingXServer,
+ false,
+ );
+ assert.ok(error);
+ assert.match(error.message, /--headless/);
+ assert.match(error.message, /Missing X server/);
+ assert.strictEqual(error.cause, missingXServer);
+ });
+
+ it('does not explain failures in headless mode', () => {
+ assert.strictEqual(
+ BrowserManager.missingDisplayLaunchError(missingXServer, true),
+ undefined,
+ );
+ });
+
+ it('does not explain unrelated failures', () => {
+ assert.strictEqual(
+ BrowserManager.missingDisplayLaunchError(
+ new Error(
+ 'Protocol error (Target.setDiscoverTargets): Target closed',
+ ),
+ false,
+ ),
+ undefined,
+ );
+ });
+ });
+
it('cannot launch multiple times with the same profile', async () => {
await runWithRetry(async () => {
const tmpDir = os.tmpdir();