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.tsindex 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.tsindex 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();