Report why the webgpu package did not load, instead of guessing
An optionalDependency that installed but whose prebuilt binary will not load
(a missing system library, say) was reported as "not installed", which sends
people to reinstall a package that is already there. Match on the resolution
error and pass anything else through with the real message. Also point at
Vulkan/Metal when Dawn loads but finds no adapter.
1 changed file+24−5
scripts/bench.tsmodified+24−5View file
@@ -87,11 +87,23 @@ async function installWebGpu(): Promise<string> {
8787 };
8888 try {
8989 mod = await import(specifier);
90- } catch {
90+ } catch (e) {
91+ // Distinguish "not installed" from "installed but the prebuilt Dawn binary
92+ // will not load" — the second is what a machine missing a system library
93+ // looks like, and reporting it as the first sends people in circles.
94+ const detail = errMsg(e);
95+ if (/Cannot find (package|module) '?webgpu'?/.test(detail)) {
96+ throw new Error(
97+ 'desktop WebGPU needs the optional `webgpu` package (prebuilt Google Dawn):\n' +
98+ ' npm install webgpu\n' +
99+ 'It is an optionalDependency, so npm can skip it silently — `npm ls webgpu`\n' +
100+ 'says whether it is there. Or run with --backend cpu.',
101+ );
102+ }
91103 throw new Error(
92- 'desktop WebGPU needs the optional `webgpu` package (prebuilt Google Dawn):\n' +
93- ' npm install webgpu\n' +
94- 'or run with --backend cpu.',
104+ `the \`webgpu\` package is installed but did not load:\n ${detail}\n` +
105+ 'That is usually the prebuilt Dawn binary missing a system library.\n' +
106+ 'Run with --backend cpu for the f64 CPU reference instead.',
95107 );
96108 }
97109 Object.assign(globalThis, mod.globals);
@@ -164,7 +176,14 @@ let adapter = '';
164176 try {
165177 if (spec.backend === 'webgpu') {
166178 runtime = await installWebGpu();
167- device = await requestShtDevice();
179+ device = await requestShtDevice().catch((e: unknown) => {
180+ throw new Error(
181+ `${errMsg(e)}\n` +
182+ ' Dawn reaches the GPU through Vulkan on Linux and Windows, Metal on macOS,\n' +
183+ " so a headless box may have no adapter at all. DAWN_FLAGS='backend=vulkan'\n" +
184+ ' makes it explain itself; --backend cpu always works.',
185+ );
186+ });
168187 adapter = await describeAdapter(device);
169188 backend = await GpuBackend.create(device, cfg);
170189 } else {