GPUUncapturedErrorEvent.error — Eigenschaft · JavaScript-Referenz

Signatur

GPUUncapturedErrorEvent.error

Beschreibung

Wenn auf einem GPUDevice ein Validierungs-, Speicher- oder interner Fehler auftritt und kein Fehlerbereich ihn abfängt (kein passendes pushErrorScope()/popErrorScope()), löst das Gerät das Ereignis uncapturederror aus. Das dabei übergebene GPUUncapturedErrorEvent enthält den eigentlichen Fehler in der Eigenschaft error.

Der Wert ist eine Instanz einer Unterklasse von GPUError:

GPUValidationError: ungültige API-Nutzung, z. B. falsche Pufferflags, nicht passende Bind-Group-Layouts oder Shader-Kompilierfehler.
GPUOutOfMemoryError: Es konnte nicht genug GPU-Speicher reserviert werden.
GPUInternalError: Fehler in der Implementierung oder überschrittene Systemgrenzen, obwohl die Validierung bestanden wurde.

Die Eigenschaft message des Fehlers enthält eine für Menschen lesbare Beschreibung. Sie ist zum Debuggen gedacht, ihr Format ist nicht standardisiert und kann sich zwischen Browsern unterscheiden. Um die Fehlerart zu bestimmen, nutzt du instanceof und wertest nicht den Nachrichtentext aus.

Typische Einsatzzwecke: zentrales Protokollieren aller nicht abgefangenen GPU-Fehler während der Entwicklung, Weitermelden an ein Fehler-Monitoring und das Erkennen von Speichermangel im laufenden Betrieb.

Rückgabewert

Typ

GPUError (GPUValidationError | GPUOutOfMemoryError | GPUInternalError)

Beschreibung

Das Fehlerobjekt. Seine Eigenschaft message (string) beschreibt den Fehler. Die Eigenschaft ist schreibgeschützt.

Beispiele

Nicht abgefangene Fehler per 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) => {
  console.error('WebGPU-Fehler:', event.error.message);
});

// Absichtlich ungültig: Die Puffergröße ist kein Vielfaches von 4, obwohl mappedAtCreation gesetzt ist
device.createBuffer({ size: 3, usage: GPUBufferUsage.VERTEX, mappedAtCreation: true });

WebGPU-Fehler: (browserabhängige Meldung, z. B. "Buffer size (3) is not a multiple of 4 ...")

Fehlerart mit instanceof unterscheiden (on-Property)

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

device.onuncapturederror = ({ error }) => {
  if (error instanceof GPUValidationError) {
    console.warn('Validierungsfehler:', error.message);
  } else if (error instanceof GPUOutOfMemoryError) {
    console.error('GPU-Speicher erschöpft – Texturqualität wird reduziert');
  } else if (error instanceof GPUInternalError) {
    console.error('Interner GPU-Fehler:', error.message);
  }
};

An Fehler-Monitoring melden und Listener wieder entfernen

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

const reportGpuError = (event) => {
  const { error } = event;
  // preventDefault() unterdrückt die Standardausgabe des Browsers in der Konsole
  event.preventDefault();
  navigator.sendBeacon('/api/gpu-errors', JSON.stringify({
    type: error.constructor.name,
    message: error.message,
    time: Date.now()
  }));
};

device.addEventListener('uncapturederror', reportGpuError);

// Später, z. B. beim Abbauen der Szene:
device.removeEventListener('uncapturederror', reportGpuError);

// Wichtig · Fallstricke

Fehlerbereiche haben Vorrang: Fängt ein mit pushErrorScope() geöffneter Bereich den Fehler ab, wird kein uncapturederror-Ereignis ausgelöst. Für gezielte Prüfungen einzelner Aufrufe sind Fehlerbereiche besser geeignet, das Ereignis dient als Auffangnetz.
Asynchron: WebGPU-Fehler werden nicht sofort geworfen, sondern später gemeldet. Der Aufruf, der den Fehler verursacht hat, läuft ohne Ausnahme weiter, deshalb gibt es keinen Stacktrace zur Fehlerquelle.
message nicht maschinell auswerten: Der Text ist nicht standardisiert und kann sich zwischen Browsern und Versionen ändern. Die Fehlerart bestimmst du mit instanceof.
Gerätverlust ist kein uncapturederror: Geht das Gerät verloren, wird das Promise GPUDevice.lost erfüllt. Diesen Fall musst du getrennt behandeln.
Die Browser können die Anzahl gemeldeter Fehler begrenzen, damit die Konsole nicht überläuft. Rechne also nicht damit, dass jeder einzelne Fehler ankommt.
Kompatibilität: WebGPU gibt es nur in sicheren Kontexten und noch nicht in allen Browsern bzw. auf allen Plattformen. Prüfe die Unterstützung vorher mit navigator.gpu. Die Eigenschaft ist auch in Web Workern verfügbar.

Siehe auch

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