Skip to content

Commit 0d16f19

Browse files
committed
fix(cli): surface HYPERFRAMES_BROWSER_PATH hint on macOS <13 chrome-headless-shell dyld crash
Field feedback (#hyperframes-cli-feedback ts=1784227832, darwin/x64, macOS 12, HyperFrames CLI 0.7.60) hit `dyld: Symbol not found: _kVTCompressionPropertyKey_ReferenceBufferCount` from VideoToolbox when launching the pinned chrome-headless-shell mac-152.0.7928.2. The symbol is macOS-13-only, so older hosts abort the binary at dyld load before any browser process starts. The reporter recovered by installing an older shell (`@puppeteer/browsers install chrome-headless-shell@150`) and pointing `PRODUCER_HEADLESS_SHELL_PATH` at it. Their check/snapshot commands accepted that older cached shell (they do not force the pinned build), but the render command requires v152 via `preferManagedChrome: true` and could not fall back on its own. The generic "Try --docker" hint didn't name any of the browser-path env vars. Sibling failure mode to the download-time hint added in #2443 and the closed-with-invite #2078 (SIGTRAP at launch on macOS arm64), and the in-flight #2481 (Windows STATUS_STACK_BUFFER_OVERRUN); same `HYPERFRAMES_BROWSER_PATH` remediation, different trigger + platform. The match is gated on: 1. Puppeteer launch-failure wrapper text 2. dyld Symbol-not-found signal 3. a macOS-13-only symbol OR the VideoToolbox framework so unrelated darwin launch failures do not mis-fire the hint. The symbol name is macOS-version-specific by construction — if a user's dyld cannot find `_kVTCompressionPropertyKey_ReferenceBufferCount` their host is <13, no separate `os.release()` gate needed. - Signed-off-by: Via -
1 parent 4b91353 commit 0d16f19

3 files changed

Lines changed: 182 additions & 0 deletions

File tree

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
import { describe, it, expect } from "vitest";
2+
import {
3+
isMacosOldChromeCrashError,
4+
macosOldChromeCrashRemediation,
5+
} from "./macosOldChromeCrash.js";
6+
7+
describe("isMacosOldChromeCrashError", () => {
8+
it("matches Puppeteer launch-failure wrapper + dyld Symbol-not-found + macOS-13 VideoToolbox symbol", () => {
9+
expect(
10+
isMacosOldChromeCrashError(
11+
"Failed to launch the browser process!\n" +
12+
"dyld: Symbol not found: _kVTCompressionPropertyKey_ReferenceBufferCount\n" +
13+
" Referenced from: /Users/x/.cache/puppeteer/chrome-headless-shell/mac-152.0.7928.2/chrome-headless-shell\n" +
14+
" Expected in: /System/Library/Frameworks/VideoToolbox.framework/Versions/A/VideoToolbox",
15+
),
16+
).toBe(true);
17+
});
18+
19+
it("matches the VideoToolbox framework signal even without the exact ReferenceBufferCount symbol name", () => {
20+
// Future pinned builds may hit a sibling VT symbol from the same framework
21+
// (they all migrated to macOS 13); the framework signal is enough to fire
22+
// the same remediation.
23+
expect(
24+
isMacosOldChromeCrashError(
25+
"Failed to launch the browser process. Symbol not found: _kVTSomeFutureSymbol from VideoToolbox",
26+
),
27+
).toBe(true);
28+
});
29+
30+
it("does not match a launch failure without dyld Symbol-not-found", () => {
31+
expect(
32+
isMacosOldChromeCrashError(
33+
"Failed to launch the browser process (libnss3.so: cannot open shared object file)",
34+
),
35+
).toBe(false);
36+
});
37+
38+
it("does not match a darwin Symbol-not-found from an unrelated framework (needs different remediation)", () => {
39+
expect(
40+
isMacosOldChromeCrashError(
41+
"Failed to launch the browser process. dyld: Symbol not found: _some_libcxx_symbol from libc++.dylib",
42+
),
43+
).toBe(false);
44+
});
45+
46+
it("does not match the symbol name alone without the launch-failure wrapper", () => {
47+
expect(
48+
isMacosOldChromeCrashError(
49+
"unrelated tool crashed with Symbol not found: _kVTCompressionPropertyKey_ReferenceBufferCount",
50+
),
51+
).toBe(false);
52+
});
53+
54+
it("does not match unrelated errors", () => {
55+
expect(isMacosOldChromeCrashError("Composition HTML is empty")).toBe(false);
56+
});
57+
});
58+
59+
describe("macosOldChromeCrashRemediation", () => {
60+
it("returns undefined off darwin even for a matching error", () => {
61+
if (process.platform === "darwin") return;
62+
expect(
63+
macosOldChromeCrashRemediation(
64+
"Failed to launch the browser process. dyld: Symbol not found: _kVTCompressionPropertyKey_ReferenceBufferCount from VideoToolbox",
65+
),
66+
).toBeUndefined();
67+
});
68+
69+
it("returns undefined for non-launch errors on any platform", () => {
70+
expect(macosOldChromeCrashRemediation("Composition HTML is empty")).toBeUndefined();
71+
});
72+
73+
it("returns undefined for a launch failure without the dyld signal on any platform", () => {
74+
expect(
75+
macosOldChromeCrashRemediation(
76+
"Failed to launch the browser process (libnss3.so cannot open)",
77+
),
78+
).toBeUndefined();
79+
});
80+
81+
it("returns undefined for a darwin dyld failure from an unrelated framework", () => {
82+
if (process.platform !== "darwin") return;
83+
expect(
84+
macosOldChromeCrashRemediation(
85+
"Failed to launch the browser process. Symbol not found: _some_libcxx_symbol from libc++.dylib",
86+
),
87+
).toBeUndefined();
88+
});
89+
90+
it("mentions HYPERFRAMES_BROWSER_PATH and the PRODUCER_HEADLESS_SHELL_PATH alias when firing on darwin", () => {
91+
if (process.platform !== "darwin") return;
92+
const remediation = macosOldChromeCrashRemediation(
93+
"Failed to launch the browser process. dyld: Symbol not found: _kVTCompressionPropertyKey_ReferenceBufferCount from VideoToolbox",
94+
);
95+
expect(remediation).toBeDefined();
96+
expect(remediation).toMatch(/HYPERFRAMES_BROWSER_PATH/);
97+
expect(remediation).toMatch(/PRODUCER_HEADLESS_SHELL_PATH/);
98+
expect(remediation).toMatch(/chrome-headless-shell@150/);
99+
});
100+
});
Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
// fallow-ignore-file code-duplication
2+
/**
3+
* Detection + remediation for macOS-below-13 chrome-headless-shell dyld
4+
* launch crashes.
5+
*
6+
* Field feedback (#hyperframes-cli-feedback ts=1784227832, darwin/x64,
7+
* macOS 12, HyperFrames CLI 0.7.60) hit
8+
* `dyld: Symbol not found: _kVTCompressionPropertyKey_ReferenceBufferCount`
9+
* from `VideoToolbox` when launching the pinned
10+
* `chrome-headless-shell mac-152.0.7928.2`. The symbol was added in
11+
* macOS 13; older hosts cannot resolve it, so the binary aborts at load
12+
* before any browser process starts.
13+
*
14+
* The reporter recovered by installing an older shell (v150) via
15+
* `@puppeteer/browsers install chrome-headless-shell@150` and pointing
16+
* `PRODUCER_HEADLESS_SHELL_PATH` at it. Their check/snapshot commands
17+
* accepted that older cached shell (they don't force the pinned build),
18+
* but the render command required v152 via `preferManagedChrome: true`
19+
* and therefore could not fall back on its own. The generic
20+
* "Try --docker for containerized rendering" hint didn't name any of
21+
* the browser-path env vars, so the workaround is undiscoverable
22+
* unaided.
23+
*
24+
* Same discoverability class as #2443 (download failure), #2078 (arm64
25+
* SIGTRAP at launch), and #2481 (Windows STATUS_STACK_BUFFER_OVERRUN):
26+
* detect the launch-time crash signal, surface `HYPERFRAMES_BROWSER_PATH`
27+
* (and its `PRODUCER_HEADLESS_SHELL_PATH` alias — see #2471) with a
28+
* concrete macOS example.
29+
*
30+
* The match is gated on the Puppeteer launch-failure wrapper text AND
31+
* the dyld symbol-not-found signal AND a macOS-13-only symbol, so
32+
* unrelated darwin launch failures do not mis-fire this hint. The
33+
* symbol-name signal is macOS-version-specific by construction:
34+
* `_kVTCompressionPropertyKey_ReferenceBufferCount` only exists on
35+
* macOS 13+, so if a user's dyld cannot find it, their host is <13.
36+
* That means we do not need a separate `os.release()` gate — the
37+
* signal itself is the version discriminator.
38+
*/
39+
40+
const DYLD_SYMBOL_NOT_FOUND = /Symbol not found:/i;
41+
const MACOS_13_ONLY_SYMBOL = /_kVTCompressionPropertyKey_ReferenceBufferCount/;
42+
const VIDEO_TOOLBOX = /VideoToolbox/;
43+
44+
export function isMacosOldChromeCrashError(errorMessage: string): boolean {
45+
if (!/Failed to launch the browser process/i.test(errorMessage)) return false;
46+
if (!DYLD_SYMBOL_NOT_FOUND.test(errorMessage)) return false;
47+
// Both signals must be present. The specific macOS-13-only symbol is what
48+
// makes this hint safe to fire (any other Symbol-not-found on darwin
49+
// needs different remediation — a shared-lib install, an Xcode SDK
50+
// mismatch, etc. — none of which are fixed by HYPERFRAMES_BROWSER_PATH).
51+
// We also require VideoToolbox to catch the case where a future pinned
52+
// build hits a different `_kVT…` symbol from the same framework.
53+
return MACOS_13_ONLY_SYMBOL.test(errorMessage) || VIDEO_TOOLBOX.test(errorMessage);
54+
}
55+
56+
export function macosOldChromeCrashRemediation(errorMessage: string): string | undefined {
57+
if (process.platform !== "darwin") return undefined;
58+
if (!isMacosOldChromeCrashError(errorMessage)) return undefined;
59+
return [
60+
"chrome-headless-shell crashed at launch (macOS dyld: Symbol not found in VideoToolbox).",
61+
"The pinned Chromium build requires macOS 13+; on macOS 12 or older, install an older",
62+
"chrome-headless-shell and point hyperframes at it:",
63+
"",
64+
" npx @puppeteer/browsers install chrome-headless-shell@150",
65+
' export HYPERFRAMES_BROWSER_PATH="$HOME/.cache/puppeteer/chrome-headless-shell/mac-150.0.7422.0/chrome-headless-shell-mac-x64/chrome-headless-shell"',
66+
"",
67+
"(PRODUCER_HEADLESS_SHELL_PATH works as an alias for the same override.)",
68+
"Any working chrome-headless-shell build resolves this — the exact version above is one",
69+
"known-good macOS-12 combination. Alternatively, point HYPERFRAMES_BROWSER_PATH at your",
70+
'installed Google Chrome ("/Applications/Google Chrome.app/Contents/MacOS/Google Chrome")',
71+
"to fall back to the screenshot capture path.",
72+
].join("\n");
73+
}

‎packages/cli/src/commands/render.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -80,6 +80,7 @@ import { formatRenderOutputTimestamp } from "@hyperframes/core";
8080
import { runEnvironmentChecks } from "../browser/preflight.js";
8181
import { detectH264EncoderMode } from "../browser/ffmpeg.js";
8282
import { chromeLaunchRemediation } from "../browser/linuxDeps.js";
83+
import { macosOldChromeCrashRemediation } from "../browser/macosOldChromeCrash.js";
8384
import { killOrphanedProcesses } from "../utils/orphanCleanup.js";
8485
import {
8586
markRenderSucceeded,
@@ -2106,6 +2107,14 @@ function handleRenderError(
21062107
errorBox("Render failed — Chrome could not launch", message, remediation);
21072108
process.exit(1);
21082109
}
2110+
// macOS <13 dyld Symbol-not-found on the pinned chrome-headless-shell
2111+
// build. Different remediation shape (older shell + env-var override)
2112+
// than the Linux shared-lib install, so it lives in its own detector.
2113+
const macosRemediation = macosOldChromeCrashRemediation(message);
2114+
if (macosRemediation) {
2115+
errorBox("Render failed — Chrome could not launch", message, macosRemediation);
2116+
process.exit(1);
2117+
}
21092118
errorBox("Render failed", message, hint);
21102119
process.exit(1);
21112120
}

0 commit comments

Comments
 (0)