GPUUncapturedErrorEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface GPUUncapturedErrorEvent extends Event

Beschreibung

GPUUncapturedErrorEvent ist der Ereignistyp, den ein GPUDevice auslöst, wenn ein WebGPU-Fehler auftritt, den kein aktiver Fehlerbereich abfängt (pushErrorScope()/popErrorScope()). WebGPU-Aufrufe werfen bei Validierungs- oder Speicherfehlern meist keine Ausnahme, weil die GPU-Arbeit asynchron läuft. Die Fehler werden stattdessen über Error Scopes oder über dieses Ereignis gemeldet.

Die wichtigste Eigenschaft ist error (nur lesbar). Sie enthält ein GPUError-Objekt, genauer eine Instanz von GPUValidationError, GPUOutOfMemoryError oder GPUInternalError. Die Fehlerbeschreibung steht in error.message.

Typische Einsatzzwecke:

Telemetrie: Unerwartete Fehler im Produktivbetrieb an einen Server melden.
Fehlersuche: Während der Entwicklung alle Fehler an einer zentralen Stelle sammeln.
Auffangnetz: Fehler behandeln, die gezielt gesetzte Error Scopes nicht erfassen.

Den Handler registriert man mit device.addEventListener("uncapturederror", handler) oder über die Eigenschaft device.onuncapturederror. Den Konstruktor new GPUUncapturedErrorEvent(type, options) braucht man fast nur für Tests. Im Normalfall erzeugt der Browser das Ereignis selbst.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Nur beim Konstruktor: der Name des Ereignisses, normalerweise `"uncapturederror"`.
$options Pflicht	{ error: GPUError, bubbles?: boolean, cancelable?: boolean, composed?: boolean }		Nur beim Konstruktor: Optionen des Ereignisses. `error` ist Pflicht und enthält das zugehörige `GPUError`-Objekt. Die übrigen Felder entsprechen den Optionen von `Event`.

Rückgabewert

Typ

GPUUncapturedErrorEvent

Beschreibung

Eine Ereignisinstanz mit der nur lesbaren Eigenschaft error vom Typ GPUError.

Beispiele

Nicht abgefangene Fehler mit addEventListener protokollieren

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}`);
});

// Absichtlicher Fehler: Größe 0 mit ungültiger usage-Kombination
device.createBuffer({ size: 16, usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.MAP_WRITE });

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

Telemetrie über die on-Eigenschaft

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

device.onuncapturederror = (event) => {
  const payload = JSON.stringify({
    typ: event.error.constructor.name,
    meldung: event.error.message,
    zeit: new Date().toISOString(),
  });
  // sendBeacon funktioniert auch, wenn die Seite gerade geschlossen wird
  navigator.sendBeacon('/api/gpu-telemetrie', payload);
};

Abgrenzung zu Error Scopes

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

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

// Dieser Fehler wird vom Scope abgefangen und löst KEIN Ereignis aus
device.pushErrorScope('validation');
device.createSampler({ maxAnisotropy: 0 });
const fehler = await device.popErrorScope();
console.log('Im Scope abgefangen:', fehler?.message);

Im Scope abgefangen: maxAnisotropy (0) is less than 1. ...

Ereignis für Tests selbst erzeugen

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

device.addEventListener('uncapturederror', (e) => {
  console.log(e instanceof GPUUncapturedErrorEvent, e.error.message);
});

const event = new GPUUncapturedErrorEvent('uncapturederror', {
  error: new GPUValidationError('Testfehler'),
});
device.dispatchEvent(event);

true Testfehler

// Wichtig · Fallstricke

Kein Ersatz für Error Scopes: Das Ereignis zeigt nicht, welcher Aufruf den Fehler verursacht hat. Für gezielte Behandlung nutzt man pushErrorScope()/popErrorScope().
Konsolenausgabe: Browser geben nicht abgefangene Fehler zusätzlich in der Konsole aus. Ruft der Handler event.preventDefault() auf, unterdrückt das diese Standardausgabe. Das kann die Fehlersuche erschweren.
Rate-Limiting: Browser begrenzen die Zahl der gemeldeten Fehler, z. B. auf einige Hundert pro Gerät. Bei Fehlern im Render-Loop gehen deshalb Meldungen verloren. Auch die eigene Telemetrie sollte man drosseln.
Geräteverlust: Wird das Gerät verloren (Absturz, Treiberproblem), kommt das nicht über dieses Ereignis. Dafür gibt es das Promise device.lost.
Kompatibilität: Das Ereignis gibt es nur in Umgebungen mit WebGPU-Unterstützung, und nur in sicheren Kontexten (HTTPS). Vorher auf navigator.gpu prüfen. Die Unterstützung in Firefox und Safari ist noch neu und hängt von Plattform und Version ab.
Die Texte in error.message hängen von der Implementierung ab. Man sollte sie nicht maschinell auswerten.

Siehe auch

GPUDevice GPUError GPUValidationError GPUOutOfMemoryError GPUInternalError GPUDevice.pushErrorScope() GPUDevice.popErrorScope() GPUDevice.lost