This composition declares data-requires-webgpu, but browser

Error message

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.

What it means

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.

Source

Thrown at packages/cli/src/browser/gpuPolicy.ts:37

  return resolveBrowserGpuMode(requestedMode, { chromePath });
}

export function compositionRequiresWebGpu(html: string): boolean {
  const compositionRoot = html.match(
    /<[^>]*\bdata-composition-id(?:\s*=\s*("[^"]*"|'[^']*'|[^\s>]+))?[^>]*>/i,
  );
  return compositionRoot ? /\bdata-requires-webgpu(?:\s|=|>)/i.test(compositionRoot[0]) : false;
}

export function assertWebGpuRequirement(
  html: string,
  requestedMode: BrowserGpuMode,
  resolvedMode: ResolvedBrowserGpuMode,
): void {
  if (requestedMode !== "auto" || resolvedMode !== "software" || !compositionRequiresWebGpu(html)) {
    return;
  }
  throw new Error(
    "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.",
  );
}

View on GitHub (pinned to c2996c8626)

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).

Example fix

# before — CI host, no GPU, auto mode rejects
$ hyperframes render webgpu-comp.html
# option A: require hardware (will fail fast if truly absent)
$ PRODUCER_BROWSER_GPU_MODE=hardware hyperframes render webgpu-comp.html
# option B: test the software fallback explicitly
$ hyperframes render webgpu-comp.html --no-browser-gpu

Defensive patterns

Strategy: validation

Validate before calling

// Before capture, decide explicit GPU mode if the composition requires WebGPU.
import { compositionRequiresWebGpu } from '@hyperframes/cli/browser/gpuPolicy';
const requestedMode = compositionRequiresWebGpu(html) ? 'hardware' : 'auto';
// pass requestedMode through to the capture call so assertWebGpuRequirement does not throw on software

Type guard

function requiresWebGpu(html: string): boolean {
  const m = html.match(/<[^>]*\bdata-composition-id[^>]*>/i);
  return m ? /\bdata-requires-webgpu(?:\s|=|>)/i.test(m[0]) : false;
}

Try / catch

try {
  await captureWithGpu(html, 'auto');
} catch (err) {
  if (/data-requires-webgpu/i.test((err as Error).message)) {
    // either move to a GPU host, or explicitly request --no-browser-gpu to test fallback
  }
  throw err;
}

Prevention

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.

When it happens

Trigger: 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 `<html data-composition-id="x" data-requires-webgpu>`.

Common situations: 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.

Related errors

AI-assisted analysis of heygen-com/hyperframes@c2996c8626 (2026-08-12). Data as JSON: /api/errors/344ebdf49cefdf75. Report an issue: GitHub.