GPUDevice: uncapturederror — Ereignis · JavaScript-Referenz

Signatur

device.addEventListener("uncapturederror", handler)

Beschreibung

WebGPU meldet Validierungs-, Speicher- und interne Fehler nicht über Ausnahmen, weil die GPU-Befehle asynchron abgearbeitet werden. Stattdessen landen die Fehler entweder in einem Fehlerbereich (GPUDevice.pushErrorScope() / popErrorScope()) oder, wenn kein passender Bereich offen ist, beim Ereignis uncapturederror des jeweiligen GPUDevice.

Das Ereignisobjekt ist ein GPUUncapturedErrorEvent. Seine Eigenschaft error enthält eine Instanz von GPUValidationError, GPUOutOfMemoryError oder GPUInternalError, jeweils mit einer lesbaren message. Registrieren lässt sich der Handler per device.addEventListener("uncapturederror", handler) oder über die Eigenschaft device.onuncapturederror.

Typische Einsatzzwecke sind ein Auffangnetz für unerwartete Fehler, Telemetrie in der Produktion oder eine Entwicklungsansicht, die GPU-Fehler sichtbar macht. Für Fehler, die Sie gezielt erwarten und behandeln wollen (etwa beim Anlegen großer Puffer), sind Fehlerbereiche die bessere Wahl.

Wird preventDefault() aufgerufen, gibt der Browser die Fehlermeldung nicht zusätzlich in der Entwicklerkonsole aus.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"uncapturederror"`.
$handler Pflicht	(event: GPUUncapturedErrorEvent) => void		Callback, der ein `GPUUncapturedErrorEvent` bekommt. In `event.error` steckt der `GPUError` mit der Eigenschaft `message`.
$options	boolean \| AddEventListenerOptions	false	Übliche Listener-Optionen wie `once` oder `signal` (zum Entfernen über einen `AbortController`).

Rückgabewert

Typ

void

Beschreibung

addEventListener() gibt nichts zurück. Der Handler bekommt ein GPUUncapturedErrorEvent.

Beispiele

Globales Auffangnetz mit addEventListener

const adapter = await navigator.gpu?.requestAdapter();
if (!adapter) throw new Error('WebGPU wird nicht unterstützt');
const device = await adapter.requestDevice();

device.addEventListener('uncapturederror', (event) => {
  const { error } = event;
  const art = error.constructor.name; // z. B. GPUValidationError
  console.error(`[WebGPU] ${art}: ${error.message}`);
});

// Absichtlich ungültig: Größe ist kein Vielfaches von 4 bei MAP_WRITE+COPY_SRC-Mapping
device.createBuffer({ size: 6, usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.STORAGE });

[WebGPU] GPUValidationError: Buffer usages (BufferUsage::(MapRead|Storage)) is invalid ...

Über die on-Property mit Fehlerart-Unterscheidung

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

device.onuncapturederror = (event) => {
  event.preventDefault(); // keine doppelte Konsolenausgabe durch den Browser
  if (event.error instanceof GPUOutOfMemoryError) {
    console.warn('GPU-Speicher erschöpft – reduziere Texturqualität');
  } else if (event.error instanceof GPUValidationError) {
    console.error('Validierungsfehler:', event.error.message);
  } else {
    console.error('Interner GPU-Fehler:', event.error.message);
  }
};

// Handler später wieder entfernen
// device.onuncapturederror = null;

Fehlerbereich vs. uncapturederror und Entfernen des Listeners

const device = await (await navigator.gpu.requestAdapter()).requestDevice();
const controller = new AbortController();

device.addEventListener('uncapturederror', (e) => {
  console.log('Nicht abgefangen:', e.error.message);
}, { signal: controller.signal });

// Dieser Fehler wird vom Fehlerbereich erfasst -> KEIN uncapturederror
device.pushErrorScope('validation');
device.createTexture({ size: [0, 0], format: 'rgba8unorm', usage: 0 });
const fehler = await device.popErrorScope();
console.log('Im Bereich erfasst:', fehler?.message);

// Listener abmelden (entspricht removeEventListener)
controller.abort();

Im Bereich erfasst: Texture usage must not be 0 ...

// Wichtig · Fallstricke

Nur ein Auffangnetz: Fehler, die ein passender, offener Fehlerbereich (pushErrorScope()) erfasst, lösen das Ereignis nicht aus. Nur die Filterart des Bereichs (validation, out-of-memory, internal) entscheidet, welche Fehler er abfängt.
Asynchron: Das Ereignis kommt nicht synchron zum fehlerhaften Aufruf. Aus dem Aufrufstapel lässt sich deshalb meist nicht erkennen, welcher Aufruf den Fehler verursacht hat. Vergeben Sie label-Werte für Ressourcen, dann nennen die Fehlermeldungen diese Namen.
Kein Ersatz für Gerätverlust: Wenn das Gerät verloren geht (Treiberabsturz, destroy()), meldet das die Promise device.lost und nicht dieses Ereignis.
Die Browser begrenzen die Zahl der Konsolenmeldungen. Werten Sie Fehler deshalb selbst aus und verlassen Sie sich nicht auf die Konsole.
Kompatibilität: WebGPU ist nur in sicheren Kontexten (HTTPS) verfügbar. Chromium-Browser unterstützen es ab Version 113, Safari und Firefox erst seit Kurzem und nicht auf allen Plattformen. Prüfen Sie deshalb vorher, ob navigator.gpu vorhanden ist. In Workern steht die API ebenfalls zur Verfügung.

Siehe auch

GPUDevice GPUUncapturedErrorEvent GPUDevice.pushErrorScope() GPUDevice.popErrorScope() GPUDevice.lost GPUValidationError HIDDevice: inputreport