new GPUPipelineError() — Methode · JavaScript-Referenz

Signatur

new GPUPipelineError(message, options)

Beschreibung

Der Konstruktor GPUPipelineError() erzeugt ein Fehlerobjekt der WebGPU-API. Es erbt von DOMException und hat zusätzlich die schreibgeschützte Eigenschaft reason, die angibt, warum die Erstellung einer Pipeline fehlgeschlagen ist: "validation" (ungültige Pipeline-Beschreibung, z. B. ein fehlerhafter Shader oder unpassende Layouts) oder "internal" (Fehler in der Implementierung oder im Treiber, etwa wenn Ressourcen erschöpft sind).

Im Normalfall erzeugst du diese Objekte nicht selbst. Der Browser verwirft damit die Promises von GPUDevice.createRenderPipelineAsync() und GPUDevice.createComputePipelineAsync(). Den Konstruktor brauchst du vor allem für Tests, Mocks und eigene Abstraktionsschichten, wenn du dasselbe Fehlerformat wie der Browser weitergeben willst.

Wichtig: Anders als bei den synchronen Varianten (createRenderPipeline()) landen solche Fehler nicht im Fehler-Scope (pushErrorScope()/popErrorScope()) und lösen auch kein uncapturederror-Ereignis aus. Du musst sie über try/catch bzw. .catch() abfangen.

Parameter

Name	Typ	Default	Beschreibung
$message	string	""	Lesbare Fehlermeldung. Sie steht später in `error.message`.
$options Pflicht	object		Objekt mit der Pflicht-Eigenschaft `reason`, einem der Werte `"validation"` oder `"internal"`. Fehlt das Objekt oder ist `reason` ungültig, wird ein `TypeError` geworfen.

Beispiele

Instanz manuell erzeugen

const err = new GPUPipelineError('Shader-Modul ungültig', { reason: 'validation' });

console.log(err.name);
console.log(err.message);
console.log(err.reason);
console.log(err instanceof DOMException);

GPUPipelineError Shader-Modul ungültig validation true

Fehler bei createComputePipelineAsync() abfangen

const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.requestDevice();

const module = device.createShaderModule({
  code: '@compute @workgroup_size(64) fn main() { kaputt }' // absichtlich fehlerhaft
});

try {
  const pipeline = await device.createComputePipelineAsync({
    layout: 'auto',
    compute: { module, entryPoint: 'main' }
  });
} catch (error) {
  if (error instanceof GPUPipelineError) {
    console.warn(`Pipeline fehlgeschlagen (${error.reason}):`, error.message);
  } else {
    throw error;
  }
}

Pipeline fehlgeschlagen (validation): ...

Mock für Unit-Tests einer Pipeline-Fabrik

// Gefälschtes Device, das den Browser-Fehler nachbildet
const fakeDevice = {
  createRenderPipelineAsync: async () => {
    throw new GPUPipelineError('Treiber-Ressourcen erschöpft', { reason: 'internal' });
  }
};

const buildPipeline = async (device, descriptor) => {
  try {
    return await device.createRenderPipelineAsync(descriptor);
  } catch (e) {
    if (e instanceof GPUPipelineError && e.reason === 'internal') {
      console.log('Interner Fehler – später erneut versuchen');
      return null;
    }
    throw e;
  }
};

console.log(await buildPipeline(fakeDevice, {}));

Interner Fehler – später erneut versuchen null

// Wichtig · Fallstricke

Browser-Unterstützung: WebGPU ist nur in sicheren Kontexten (HTTPS) verfügbar. Chromium unterstützt es seit Version 113. In Safari und Firefox kam die Unterstützung erst später und hängt teils von Plattform bzw. Einstellungen ab. Prüfe vorher mit 'gpu' in navigator oder typeof GPUPipelineError !== 'undefined'.
Das Argument options ist Pflicht: new GPUPipelineError('x') wirft einen TypeError.
Fehler der asynchronen Pipeline-Erstellung landen nicht in popErrorScope(). Wenn du sie nicht abfängst, bleibt das Promise unbehandelt verworfen.
Verlass dich nicht auf den Text von message, denn er ist je nach Implementierung verschieden. Entscheide im Code anhand von reason.
Bei reason: "internal" kann ein erneuter Versuch klappen, bei "validation" nicht. Dann ist die Pipeline-Beschreibung bzw. der Shader fehlerhaft.

Siehe auch

GPUPipelineError GPUPipelineError.reason GPUDevice.createRenderPipelineAsync() GPUDevice.createComputePipelineAsync() DOMException GPUError new EventSource()