Skip to content

Commit 20f45bd

Browse files
committed
fix(engine): keep WSL GPU notes true to the probe result and render mode
The WSL note now prints only when auto mode really selects software, and says whether the GPU check found no GPU or could not finish. Explicit --browser-gpu keeps its unverified and Chrome-install advice and adds the WSL checks. The render-node check verifies group membership before suggesting usermod.
1 parent aaf7127 commit 20f45bd

5 files changed

Lines changed: 234 additions & 104 deletions

File tree

‎docs/guides/troubleshooting.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -237,10 +237,10 @@ slower on a long or effect-heavy video. The render log says so:
237237

238238
```text
239239
[hyperframes] browserGpuMode probe → software (WebGL unavailable)
240-
[hyperframes] WSL: Chrome could not use the GPU, so this render uses software WebGL ...
240+
[hyperframes] WSL: the GPU check found no hardware GPU, so this render uses software WebGL ...
241241
```
242242

243-
The second line says what HyperFrames checked. If it says your user is not in
243+
The lines after it say what HyperFrames checked. If they say your user is not in
244244
the `render` group, add yourself, restart WSL, and render again:
245245

246246
```bash

‎packages/engine/src/services/browserManager.test.ts‎

Lines changed: 90 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -369,6 +369,13 @@ describe("resolveBrowserGpuMode", () => {
369369
return { close, launch };
370370
};
371371

372+
const notWsl = {
373+
platform: "linux" as const,
374+
release: "6.8.0-45-generic",
375+
readProcVersion: () => "Linux version 6.8.0-45-generic",
376+
renderNodeAccess: () => ({ state: "read-write" as const }),
377+
};
378+
372379
beforeEach(() => {
373380
_resetAutoBrowserGpuModeCacheForTests();
374381
});
@@ -414,15 +421,15 @@ describe("resolveBrowserGpuMode", () => {
414421
renderer: "ANGLE (Google, Vulkan 1.3.0 (SwiftShader Device))",
415422
});
416423
const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
417-
const mode = await resolveBrowserGpuMode("hardware", { platform: "linux" });
424+
const mode = await resolveBrowserGpuMode("hardware", { platform: "linux", wslHost: notWsl });
418425
expect(mode).toBe("hardware");
419426
const warning = warn.mock.calls.map((call) => String(call[0])).join("\n");
420427
expect(warning).toContain("browserGpuMode=hardware was requested");
421428
expect(warning).toContain("--gpus all");
422429
// Once per process, not once per worker — the render path resolves the
423430
// mode for the probe browser plus every parallel worker.
424-
await resolveBrowserGpuMode("hardware", { platform: "linux" });
425-
await resolveBrowserGpuMode("hardware", { platform: "linux" });
431+
await resolveBrowserGpuMode("hardware", { platform: "linux", wslHost: notWsl });
432+
await resolveBrowserGpuMode("hardware", { platform: "linux", wslHost: notWsl });
426433
expect(warn).toHaveBeenCalledTimes(1);
427434
});
428435

@@ -440,7 +447,9 @@ describe("resolveBrowserGpuMode", () => {
440447
renderer: "ANGLE (Google, Vulkan 1.3.0 (SwiftShader Device))",
441448
});
442449
const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
443-
expect(await resolveBrowserGpuMode("hardware", { platform: "darwin" })).toBe("hardware");
450+
expect(await resolveBrowserGpuMode("hardware", { platform: "darwin", wslHost: notWsl })).toBe(
451+
"hardware",
452+
);
444453
const warning = String(warn.mock.calls[0]?.[0]);
445454
expect(warning).toContain("host exposes a GPU");
446455
expect(warning).not.toContain("--gpus all");
@@ -454,7 +463,9 @@ describe("resolveBrowserGpuMode", () => {
454463
launch: vi.fn().mockRejectedValue(new Error("spawn ENOENT /bad/chrome")),
455464
} as unknown as PuppeteerNode);
456465
const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
457-
expect(await resolveBrowserGpuMode("hardware", { platform: "linux" })).toBe("hardware");
466+
expect(await resolveBrowserGpuMode("hardware", { platform: "linux", wslHost: notWsl })).toBe(
467+
"hardware",
468+
);
458469
const warning = String(warn.mock.calls[0]?.[0]);
459470
expect(warning).toContain("GPU probe could not run");
460471
expect(warning).toContain("hyperframes doctor");
@@ -466,43 +477,99 @@ describe("resolveBrowserGpuMode", () => {
466477
platform: "linux" as const,
467478
release: "5.15.167.4-microsoft-standard-WSL2",
468479
readProcVersion: () => "",
469-
exists: (path: string) => path === "/dev/dri/renderD128",
470-
canOpen: () => false,
480+
renderNodeAccess: () => ({ state: "denied" as const, group: "render", userInGroup: false }),
471481
};
472-
const errorOutput = (spy: { mock: { calls: unknown[][] } }) =>
482+
const output = (spy: { mock: { calls: unknown[][] } }) =>
473483
spy.mock.calls.map((call) => String(call[0])).join("\n");
484+
const neverAnsweringProbe = () => {
485+
const launch = vi.fn().mockResolvedValue({
486+
newPage: vi.fn().mockResolvedValue({ evaluate: () => new Promise(() => {}) }),
487+
close: () => new Promise(() => {}),
488+
process: () => ({ kill: vi.fn() }),
489+
disconnect: vi.fn().mockResolvedValue(undefined),
490+
});
491+
_setPuppeteerForTests({ launch } as unknown as PuppeteerNode);
492+
};
474493

475-
it("says why auto mode fell back and how to fix it, once", async () => {
494+
it("auto mode says it fell back to software, why, and the fix, once", async () => {
476495
setMockWebGlProbe({ hasWebGL: false, vendor: "", renderer: "" });
477496
const error = vi.spyOn(console, "error").mockImplementation(() => {});
478497
expect(await resolveBrowserGpuMode("auto", { platform: "linux", wslHost })).toBe("software");
479498
await resolveBrowserGpuMode("auto", { platform: "linux", wslHost });
480-
const output = errorOutput(error);
481-
expect(output).toContain("browserGpuMode probe → software (WebGL unavailable)");
482-
expect(output).toContain('not in the "render" group');
483-
expect(output).toContain("sudo usermod -aG render $USER");
484-
expect(output.match(/usermod/g)).toHaveLength(1);
499+
const text = output(error);
500+
expect(text).toContain("browserGpuMode probe → software (WebGL unavailable)");
501+
expect(text).toContain(
502+
"WSL: the GPU check found no hardware GPU, so this render uses software",
503+
);
504+
expect(text).toContain('is not in its group ("render")');
505+
expect(text).toContain("sudo usermod -aG render $USER");
506+
expect(text.match(/usermod/g)).toHaveLength(1);
485507
});
486508

487-
it("explains a probe that timed out too", async () => {
509+
it("auto mode says the check did not finish when the probe page times out", async () => {
510+
vi.useFakeTimers();
511+
try {
512+
neverAnsweringProbe();
513+
const error = vi.spyOn(console, "error").mockImplementation(() => {});
514+
const mode = resolveBrowserGpuMode("auto", { platform: "linux", wslHost });
515+
await vi.advanceTimersByTimeAsync(15_000 + 250);
516+
await expect(mode).resolves.toBe("software");
517+
const text = output(error);
518+
expect(text).toContain("did not answer within 15000ms");
519+
expect(text).toContain("WSL: the GPU check could not finish");
520+
expect(text).not.toContain("found no hardware GPU");
521+
} finally {
522+
vi.useRealTimers();
523+
}
524+
});
525+
526+
it("explicit 'hardware' after a timeout stays unverified and never claims software", async () => {
527+
vi.useFakeTimers();
528+
try {
529+
neverAnsweringProbe();
530+
const error = vi.spyOn(console, "error").mockImplementation(() => {});
531+
const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
532+
const mode = resolveBrowserGpuMode("hardware", { platform: "linux", wslHost });
533+
await vi.advanceTimersByTimeAsync(15_000 + 250);
534+
await expect(mode).resolves.toBe("hardware");
535+
const warning = output(warn);
536+
expect(warning).toContain("hardware acceleration is UNVERIFIED");
537+
expect(warning).toContain("hyperframes doctor");
538+
expect(warning).toContain("sudo usermod -aG render $USER");
539+
expect(warning).not.toContain("found no hardware GPU");
540+
expect(output(error)).not.toContain("this render uses software");
541+
} finally {
542+
vi.useRealTimers();
543+
}
544+
});
545+
546+
it("explicit 'hardware' with a broken Chrome keeps the Chrome-install advice", async () => {
488547
_setPuppeteerForTests({
489-
launch: vi.fn().mockRejectedValue(new Error("GPU probe page did not answer")),
548+
launch: vi.fn().mockRejectedValue(new Error("spawn ENOENT /bad/chrome")),
490549
} as unknown as PuppeteerNode);
491550
const error = vi.spyOn(console, "error").mockImplementation(() => {});
492-
expect(await resolveBrowserGpuMode("auto", { platform: "linux", wslHost })).toBe("software");
493-
expect(errorOutput(error)).toContain("sudo usermod -aG render $USER");
551+
const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
552+
expect(await resolveBrowserGpuMode("hardware", { platform: "linux", wslHost })).toBe(
553+
"hardware",
554+
);
555+
const warning = output(warn);
556+
expect(warning).toContain("GPU probe could not run");
557+
expect(warning).toContain("hyperframes doctor");
558+
expect(warning).not.toContain("--gpus all");
559+
expect(output(error)).not.toContain("this render uses software");
494560
});
495561

496-
it("points explicit 'hardware' at the WSL note instead of Docker passthrough", async () => {
562+
it("explicit 'hardware' with no hardware GPU gives the WSL fix, not Docker passthrough", async () => {
497563
setMockWebGlProbe({ hasWebGL: false, vendor: "", renderer: "" });
498-
vi.spyOn(console, "error").mockImplementation(() => {});
564+
const error = vi.spyOn(console, "error").mockImplementation(() => {});
499565
const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
500566
expect(await resolveBrowserGpuMode("hardware", { platform: "linux", wslHost })).toBe(
501567
"hardware",
502568
);
503-
const warning = String(warn.mock.calls[0]?.[0]);
504-
expect(warning).toContain("WSL note above");
569+
const warning = output(warn);
570+
expect(warning).toContain("sudo usermod -aG render $USER");
505571
expect(warning).not.toContain("--gpus all");
572+
expect(output(error)).not.toContain("this render uses software");
506573
});
507574

508575
it("stays quiet when WSL hands Chrome a hardware GPU", async () => {
@@ -513,7 +580,7 @@ describe("resolveBrowserGpuMode", () => {
513580
});
514581
const error = vi.spyOn(console, "error").mockImplementation(() => {});
515582
expect(await resolveBrowserGpuMode("auto", { platform: "linux", wslHost })).toBe("hardware");
516-
expect(errorOutput(error)).not.toContain("WSL");
583+
expect(output(error)).not.toContain("WSL");
517584
});
518585
});
519586

‎packages/engine/src/services/browserManager.ts‎

Lines changed: 46 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ import { homedir } from "os";
1515
import { chromeMajorCeiling, exceedsChromeCeiling } from "./chromeHostCeiling.js";
1616
import { DEFAULT_CONFIG, type EngineConfig } from "../config.js";
1717
import { getSystemTotalMb, LOW_MEMORY_TOTAL_MB_THRESHOLD } from "./systemMemory.js";
18-
import { describeWslGpuFallback, type WslHostFacts } from "./wslHost.js";
18+
import { describeWslGpuAccess, type WslHostFacts } from "./wslHost.js";
1919
import {
2020
BrowserLeasePool,
2121
type BrowserLaunchFingerprint,
@@ -497,8 +497,8 @@ export const _closeBrowserAfterFailedProbeForTests = closeBrowserAfterFailedProb
497497
interface GpuProbeOutcome {
498498
mode: "software" | "hardware";
499499
cause?: "no-gpu" | "probe-error";
500-
/** Set when the fallback happened under WSL; already printed by the probe. */
501-
wslNote?: string;
500+
/** Under WSL, what we checked on its GPU path (see describeWslGpuAccess). */
501+
wslAccess?: string[];
502502
}
503503

504504
/**
@@ -518,6 +518,7 @@ let _autoBrowserGpuModeCache: Promise<GpuProbeOutcome> | undefined;
518518
export function _resetAutoBrowserGpuModeCacheForTests(): void {
519519
_autoBrowserGpuModeCache = undefined;
520520
_unverifiedHardwareGpuWarned = false;
521+
_wslSoftwareNoteLogged = false;
521522
}
522523

523524
async function getPuppeteerOrNull(): Promise<PuppeteerNode | null> {
@@ -575,17 +576,16 @@ async function probeAutoBrowserGpuMode(options: GpuProbeOptions): Promise<GpuPro
575576
const resolved = resolveWebGlProbeMode(info);
576577
logResolvedBrowserGpuMode(resolved, describeWebGlProbe(info));
577578
if (resolved === "hardware") return { mode: "hardware" };
578-
return { mode: "software", cause: "no-gpu", wslNote: logWslGpuFallback(options) };
579+
return { mode: "software", cause: "no-gpu", ...wslAccess(options) };
579580
} catch (err) {
580581
logResolvedBrowserGpuMode("software", formatProbeFailure(err));
581-
return { mode: "software", cause: "probe-error", wslNote: logWslGpuFallback(options) };
582+
return { mode: "software", cause: "probe-error", ...wslAccess(options) };
582583
}
583584
}
584585

585-
function logWslGpuFallback(options: GpuProbeOptions): string | undefined {
586-
const note = describeWslGpuFallback(options.wslHost) ?? undefined;
587-
if (note) console.error(note);
588-
return note;
586+
function wslAccess(options: GpuProbeOptions): Pick<GpuProbeOutcome, "wslAccess"> {
587+
const lines = describeWslGpuAccess(options.wslHost);
588+
return lines ? { wslAccess: lines } : {};
589589
}
590590

591591
/**
@@ -621,7 +621,15 @@ export function resolveBrowserGpuMode(
621621
if (mode === "software") return Promise.resolve(mode);
622622

623623
_autoBrowserGpuModeCache ??= probeAutoBrowserGpuMode(options);
624-
if (mode === "auto") return _autoBrowserGpuModeCache.then((probed) => probed.mode);
624+
if (mode === "auto") {
625+
return _autoBrowserGpuModeCache.then((probed) => {
626+
if (probed.mode === "software" && probed.wslAccess && !_wslSoftwareNoteLogged) {
627+
_wslSoftwareNoteLogged = true;
628+
console.error(buildWslSoftwareNote(probed));
629+
}
630+
return probed.mode;
631+
});
632+
}
625633

626634
return _autoBrowserGpuModeCache.then((probed) => {
627635
// Warn once per cache lifetime, not once per caller: `createCaptureSession`
@@ -640,6 +648,21 @@ export function resolveBrowserGpuMode(
640648
* cache lifetime (re-armed by `_resetAutoBrowserGpuModeCacheForTests`).
641649
*/
642650
let _unverifiedHardwareGpuWarned = false;
651+
let _wslSoftwareNoteLogged = false;
652+
653+
/** Auto mode under WSL selected software: say so, with what we checked. */
654+
function buildWslSoftwareNote({ cause, wslAccess = [] }: GpuProbeOutcome): string {
655+
const check =
656+
cause === "probe-error"
657+
? "the GPU check could not finish (see the probe line above)"
658+
: "the GPU check found no hardware GPU";
659+
return [
660+
`[hyperframes] WSL: ${check}, so this render uses software WebGL (SwiftShader) and runs ` +
661+
"at CPU speed.",
662+
...wslAccess,
663+
" Pass --no-browser-gpu to skip the GPU check and render in software.",
664+
].join("\n");
665+
}
643666

644667
/**
645668
* Warning text for "you asked for hardware GPU and we could not confirm it".
@@ -652,15 +675,8 @@ let _unverifiedHardwareGpuWarned = false;
652675
*/
653676
function buildUnverifiedHardwareGpuWarning(
654677
platform: NodeJS.Platform | string,
655-
{ cause, wslNote }: GpuProbeOutcome,
678+
{ cause, wslAccess }: GpuProbeOutcome,
656679
): string {
657-
if (wslNote) {
658-
return (
659-
"[hyperframes] browserGpuMode=hardware was requested, but the GPU probe found no usable " +
660-
"GPU under WSL, so the capture will likely run at CPU speed. Honouring the explicit " +
661-
"request anyway. The WSL note above says what was checked and how to fix it."
662-
);
663-
}
664680
if (cause === "probe-error") {
665681
return (
666682
"[hyperframes] browserGpuMode=hardware was requested, but the GPU probe could not run, " +
@@ -670,22 +686,28 @@ function buildUnverifiedHardwareGpuWarning(
670686
"`browserGpuMode probe → software (probe failed ...)` line above for the underlying " +
671687
"error, which usually means Chrome could not launch (bad HYPERFRAMES_BROWSER_PATH, " +
672688
"missing shared libraries, or a denied sandbox) rather than a GPU problem.\n" +
673-
" Run `hyperframes doctor` to check the Chrome install."
689+
" Run `hyperframes doctor` to check the Chrome install." +
690+
(wslAccess
691+
? ["", " Under WSL, a GPU path that is slow to start or unreachable can also cause it:"]
692+
.concat(wslAccess)
693+
.join("\n")
694+
: "")
674695
);
675696
}
676697
const remediation =
677-
platform === "linux"
678-
? "Inside Docker, the container needs GPU passthrough: `--gpus all` with the NVIDIA " +
698+
wslAccess?.join("\n") ??
699+
(platform === "linux"
700+
? " Inside Docker, the container needs GPU passthrough: `--gpus all` with the NVIDIA " +
679701
"Container Toolkit installed, or `--device /dev/dri` for Mesa/AMD/Intel. The image " +
680702
"also needs the matching userspace driver + libEGL. Verify with " +
681703
"`hyperframes render --browser-gpu` and watch for this warning disappearing."
682-
: "Check that the host exposes a GPU to this process and that the graphics drivers are " +
683-
"installed.";
704+
: " Check that the host exposes a GPU to this process and that the graphics drivers " +
705+
"are installed.");
684706
return (
685707
"[hyperframes] browserGpuMode=hardware was requested, but the WebGL probe found no " +
686708
"hardware GPU, so Chrome will silently fall back to software WebGL and the capture will " +
687709
"run at CPU speed. Honouring the explicit request anyway.\n" +
688-
` ${remediation}\n` +
710+
`${remediation}\n` +
689711
" Pass --no-browser-gpu to select deterministic SwiftShader instead of waiting on a " +
690712
"hardware path that is not there."
691713
);

0 commit comments

Comments
 (0)