fix(engine): diagnose a failed Chrome launch with the env it had (#7634)

The startup diagnosis rebuilt its env from process.env, so a launch that
dropped WAYLAND_DISPLAY or the SwiftShader Vulkan pins was diagnosed with
them restored. The engine and CLI now pass the failed attempt's env through
explainChromeLaunchFailure; process.env stays the fallback when no env is given.

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
James Russo
2026-11-13 01:36:12 +00:00
committed by GitHub
co-authored by Claude Opus 5.5
parent 2591abfbf0
commit 9701f4bbf3
5 changed files with 73 additions and 8 deletions
@@ -57,5 +57,38 @@ describe.runIf(process.platform === "linux")(
expect(failure?.message).toContain("exited with code 3");
expect(failure?.message).toMatch(/--no-sandbox/);
}, 60_000);
it("starts the diagnosis with the launch's env, not process.env", async () => {
vi.stubEnv("HYPERFRAMES_CHROME_SANDBOX", "");
vi.stubEnv("WAYLAND_DISPLAY", "wayland-from-process-env");
vi.spyOn(console, "warn").mockImplementation(() => {});
const real = (await import("puppeteer-core")).default;
const puppeteer = {
launch: async () => {
throw closedTarget();
},
defaultArgs: (options: Parameters<PuppeteerNode["defaultArgs"]>[0]) =>
real.defaultArgs(options),
} as unknown as PuppeteerNode;
const path = join(mkdtempSync(join(tmpdir(), "hf-fake-chrome-")), "chrome");
writeFileSync(
path,
"#!/usr/bin/env node\nconsole.error('wayland=' + process.env.WAYLAND_DISPLAY); process.exit(3);\n",
);
chmodSync(path, 0o755);
const failure = await launchManagedBrowser(puppeteer, {
executablePath: path,
headless: true,
args: ["--headless"],
env: { PATH: process.env.PATH },
}).then(
() => undefined,
(error: unknown) => error as Error,
);
expect(failure?.message).toContain("wayland=undefined");
expect(failure?.message).not.toContain("wayland-from-process-env");
}, 60_000);
},
);
+4 -1
View File
@@ -148,7 +148,10 @@ async function withStartupDiagnosis(
const abort = new AbortController();
diagnosing.add(abort);
try {
return await explainChromeLaunchFailure(error, options.executablePath, args, abort.signal);
return await explainChromeLaunchFailure(error, options.executablePath, args, {
signal: abort.signal,
env: options.env,
});
} finally {
diagnosing.delete(abort);
}
@@ -9,11 +9,18 @@ import {
import { _resetChromeSandboxFallbackForTests } from "./chromeSandbox.js";
const explained = vi.hoisted(() => [] as (readonly string[] | undefined)[]);
const explainedEnvs = vi.hoisted(() => [] as (NodeJS.ProcessEnv | undefined)[]);
vi.mock("./chromeStartup.js", async (importActual) => ({
...(await importActual<typeof import("./chromeStartup.js")>()),
explainChromeLaunchFailure: async (error: unknown, _path: unknown, args?: readonly string[]) => {
explainChromeLaunchFailure: async (
error: unknown,
_path: unknown,
args?: readonly string[],
options?: { env?: NodeJS.ProcessEnv },
) => {
explained.push(args);
explainedEnvs.push(options?.env);
return error;
},
}));
@@ -24,6 +31,7 @@ const closedTarget = () =>
describe("the startup diagnosis after a sandboxed launch and its retry both fail", () => {
beforeEach(() => {
explained.length = 0;
explainedEnvs.length = 0;
_resetChromeSandboxFallbackForTests();
vi.stubEnv("PRODUCER_HEADLESS_SHELL_PATH", process.execPath);
vi.stubEnv("HYPERFRAMES_CHROME_SANDBOX", "");
@@ -57,4 +65,20 @@ describe("the startup diagnosis after a sandboxed launch and its retry both fail
expect(explained).toHaveLength(1);
expect(explained[0]).toEqual(expect.arrayContaining(["--headless", "--no-sandbox"]));
});
it("diagnoses with the env the failed launch had, not one rebuilt from process.env", async () => {
vi.stubEnv("VK_DRIVER_FILES", "/usr/share/vulkan/icd.d/radeon_icd.json");
const launch = vi.fn<(options: LaunchOptions) => Promise<never>>();
launch.mockRejectedValue(closedTarget());
const defaultArgs = vi.fn(async (options: { args?: string[] }) => options.args ?? []);
_setPuppeteerForTests({ launch, defaultArgs } as unknown as PuppeteerNode);
await acquireBrowser(["--headless", "--use-angle=swiftshader"], {
forceScreenshot: true,
}).catch(() => undefined);
const attemptEnv = launch.mock.calls.at(-1)?.[0].env;
expect(attemptEnv).not.toHaveProperty("VK_DRIVER_FILES");
expect(explainedEnvs).toEqual([attemptEnv]);
});
});
@@ -945,7 +945,7 @@ async function launchBrowser(
headless: true,
args: withHyperframesBrowserMarker(attempted),
});
throw await explainChromeLaunchFailure(error, fingerprint.executablePath, defaults);
throw await explainChromeLaunchFailure(error, fingerprint.executablePath, defaults, { env });
});
};
const probe = (target: Browser, timeoutMs?: number) =>
+10 -5
View File
@@ -46,11 +46,16 @@ function tail(stderr: string): string {
.join("\n");
}
/** Starts the browser once more with the failed launch's flags and says how it ended. */
/** Starts the browser again with the failed launch's flags and env, and says how it ended. */
export async function diagnoseChromeStartup(
executablePath: string,
args: readonly string[],
options: { timeoutMs?: number; platform?: NodeJS.Platform; signal?: AbortSignal } = {},
options: {
timeoutMs?: number;
platform?: NodeJS.Platform;
signal?: AbortSignal;
env?: NodeJS.ProcessEnv;
} = {},
): Promise<string> {
const profile = mkdtempSync(join(tmpdir(), "hf-chrome-probe-"));
const timeoutMs = options.timeoutMs ?? PROBE_TIMEOUT_MS;
@@ -58,7 +63,7 @@ export async function diagnoseChromeStartup(
return await new Promise<string>((resolve) => {
let stderr = "";
const child = spawn(executablePath, startupArgs(args, profile), {
env: buildChromeLaunchEnv(),
env: buildChromeLaunchEnv(options.env),
stdio: ["ignore", "ignore", "pipe"],
windowsHide: true,
});
@@ -104,7 +109,7 @@ export async function explainChromeLaunchFailure(
error: unknown,
executablePath: string | undefined,
args: readonly string[] | undefined,
signal?: AbortSignal,
{ signal, env }: { signal?: AbortSignal; env?: NodeJS.ProcessEnv } = {},
): Promise<unknown> {
if (!(error instanceof Error)) return error;
const { code, errno, syscall } = error as NodeJS.ErrnoException;
@@ -117,6 +122,6 @@ export async function explainChromeLaunchFailure(
{ cause: error },
);
if (!executablePath) return error;
const diagnosis = await diagnoseChromeStartup(executablePath, args ?? [], { signal });
const diagnosis = await diagnoseChromeStartup(executablePath, args ?? [], { signal, env });
return new Error(`${error.message}\n${diagnosis}`, { cause: error });
}