{"record":{"id":"344ebdf49cefdf75","repo":"heygen-com/hyperframes","slug":"this-composition-declares-data-requires-webgpu-bu","errorCode":null,"errorMessage":"This composition declares data-requires-webgpu, but browser GPU auto-detection found no hardware GPU. Run on a WebGPU-capable host or set PRODUCER_BROWSER_GPU_MODE=hardware (or pass --browser-gpu on commands that support it) to require hardware explicitly; use --no-browser-gpu only when intentionally testing the composition's software fallback.","messagePattern":"This composition declares data-requires-webgpu, but browser GPU auto-detection found no hardware GPU\\. Run on a WebGPU-capable host or set PRODUCER_BROWSER_GPU_MODE=hardware \$or pass --browser-gpu on commands that support it\$ to require hardware explicitly; use --no-browser-gpu only when intentionally testing the composition's software fallback\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/cli/src/browser/gpuPolicy.ts","lineNumber":37,"sourceCode":" return resolveBrowserGpuMode(requestedMode, { chromePath });\n}\n\nexport function compositionRequiresWebGpu(html: string): boolean {\n const compositionRoot = html.match(\n /<[^>]*\\bdata-composition-id(?:\\s*=\\s*(\"[^\"]*\"|'[^']*'|[^\\s>]+))?[^>]*>/i,\n );\n return compositionRoot ? /\\bdata-requires-webgpu(?:\\s|=|>)/i.test(compositionRoot[0]) : false;\n}\n\nexport function assertWebGpuRequirement(\n html: string,\n requestedMode: BrowserGpuMode,\n resolvedMode: ResolvedBrowserGpuMode,\n): void {\n if (requestedMode !== \"auto\" || resolvedMode !== \"software\" || !compositionRequiresWebGpu(html)) {\n return;\n }\n throw new Error(\n \"This composition declares data-requires-webgpu, but browser GPU auto-detection found no hardware GPU. \" +\n \"Run on a WebGPU-capable host or set PRODUCER_BROWSER_GPU_MODE=hardware \" +\n \"(or pass --browser-gpu on commands that support it) to require hardware explicitly; \" +\n \"use --no-browser-gpu only when intentionally testing the composition's software fallback.\",\n );\n}\n","sourceCodeStart":19,"sourceCodeEnd":44,"githubUrl":"https://github.com/heygen-com/hyperframes/blob/c2996c8626135db5253519359d8a063d3bafad8d/packages/cli/src/browser/gpuPolicy.ts#L19-L44","documentation":"Thrown by assertWebGpuRequirement() when three conditions coincide: the composition root element declares data-requires-webgpu, the requested GPU mode is 'auto', and browser GPU auto-detection resolved to 'software' (no hardware GPU found). The composition explicitly requires WebGPU, so silently running on a software rasterizer would produce broken output; the error tells the user to either move to WebGPU-capable hardware or explicitly request hardware/software mode.","triggerScenarios":"assertWebGgpuRequirement(html, requestedMode, resolvedMode) is called after resolveCaptureBrowserGpuMode; on a CI/headless host without a GPU, requestedMode='auto' resolves to 'software', and the HTML contains something like ``.","commonSituations":"Running a WebGPU shader composition in a CI runner (no GPU), a container without GPU passthrough, or a remote server; the user authored a data-requires-webgpu composition and forgot to set --browser-gpu on a GPU box where detection still failed.","solutions":["Run on a host with a real GPU (or enable GPU passthrough in your container/VM).","Set PRODUCER_BROWSER_GPU_MODE=hardware (or pass --browser-gpu) to require hardware explicitly so detection failure surfaces earlier and differently.","If you are intentionally testing the composition's software fallback, pass --no-browser-gpu to suppress this guard (only when the composition has a graceful software path)."],"exampleFix":"# before — CI host, no GPU, auto mode rejects\n$ hyperframes render webgpu-comp.html\n# option A: require hardware (will fail fast if truly absent)\n$ PRODUCER_BROWSER_GPU_MODE=hardware hyperframes render webgpu-comp.html\n# option B: test the software fallback explicitly\n$ hyperframes render webgpu-comp.html --no-browser-gpu","handlingStrategy":"validation","validationCode":"// Before capture, decide explicit GPU mode if the composition requires WebGPU.\nimport { compositionRequiresWebGpu } from '@hyperframes/cli/browser/gpuPolicy';\nconst requestedMode = compositionRequiresWebGpu(html) ? 'hardware' : 'auto';\n// pass requestedMode through to the capture call so assertWebGpuRequirement does not throw on software","typeGuard":"function requiresWebGpu(html: string): boolean {\n const m = html.match(/<[^>]*\\bdata-composition-id[^>]*>/i);\n return m ? /\\bdata-requires-webgpu(?:\\s|=|>)/i.test(m[0]) : false;\n}","tryCatchPattern":"try {\n await captureWithGpu(html, 'auto');\n} catch (err) {\n if (/data-requires-webgpu/i.test((err as Error).message)) {\n // either move to a GPU host, or explicitly request --no-browser-gpu to test fallback\n }\n throw err;\n}","preventionTips":["Run WebGPU compositions on hosts with a real GPU or GPU passthrough.","In CI, skip or xfail WebGPU compositions on software-only runners.","When authoring, set data-requires-webgpu only if the composition truly has no software fallback."],"tags":["webgpu","gpu","browser","composition","environment","render"],"backgroundTag":null,"analyzedSha":"c2996c8626135db5253519359d8a063d3bafad8d","analyzedAt":"2026-08-12T22:18:56.877Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}