GPUError.message — Eigenschaft · JavaScript-Referenz

Signatur

GPUError.message

Beschreibung

Die Eigenschaft message des Interfaces GPUError enthält eine für Menschen lesbare Beschreibung des Fehlers, den die WebGPU-Implementierung festgestellt hat. GPUError ist die Basis von GPUValidationError, GPUOutOfMemoryError und GPUInternalError. Alle drei erben message.

An ein GPUError-Objekt kommt man auf zwei Wegen: über GPUDevice.popErrorScope(), nachdem man mit pushErrorScope() einen Fehlerbereich geöffnet hat, oder über das Ereignis uncapturederror am GPUDevice. Dort liegt der Fehler in event.error.

Der Text ist nur zur Fehlersuche gedacht. Er wird vom Browser erzeugt, nennt oft die betroffenen Objekte mit ihrem label und kann je nach Browser, Version und Treiber anders lauten. Um Fehler im Programm zu unterscheiden, prüft man deshalb den Fehlertyp mit instanceof und nicht den Inhalt von message.

Rückgabewert

Typ

string

Beschreibung

Eine vom Browser erzeugte, lesbare Fehlerbeschreibung. Sie ist schreibgeschützt und hat kein festgelegtes Format.

Beispiele

Validierungsfehler mit einem Fehlerbereich abfangen

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

device.pushErrorScope('validation');

// Ungültig: Die Nutzungsart MAP_READ darf nur mit COPY_DST kombiniert werden
device.createBuffer({
  label: 'Kaputter Puffer',
  size: 16,
  usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.VERTEX
});

const error = await device.popErrorScope();
if (error) {
  console.error(`Validierung fehlgeschlagen: ${error.message}`);
}

Validierung fehlgeschlagen: Buffer usages (BufferUsage::(MapRead|Vertex)) is invalid. ... [Buffer "Kaputter Puffer"] (genauer Text hängt vom Browser ab)

Nicht abgefangene Fehler zentral protokollieren

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

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

// Löst einen Fehler aus: Eine Textur mit Breite 0 ist ungültig
device.createTexture({
  size: [0, 0],
  format: 'rgba8unorm',
  usage: GPUTextureUsage.TEXTURE_BINDING
});

[WebGPU] GPUValidationError: ... (Text hängt vom Browser ab)

Speichermangel erkennen: Typ prüfen, message nur protokollieren

const allocate = async (device, size) => {
  device.pushErrorScope('out-of-memory');
  const buffer = device.createBuffer({ size, usage: GPUBufferUsage.STORAGE });
  const error = await device.popErrorScope();

  if (error instanceof GPUOutOfMemoryError) {
    console.info('Zu wenig GPU-Speicher:', error.message);
    buffer.destroy();
    return null; // Aufrufer kann es mit einer kleineren Größe erneut versuchen
  }
  return buffer;
};

const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.requestDevice();
const buf = await allocate(device, 256 * 1024 * 1024);
console.log(buf ? 'Puffer angelegt' : 'Fallback nötig');

Puffer angelegt

// Wichtig · Fallstricke

Das Format ist nicht festgelegt: Der Inhalt von message ist je nach Implementierung verschieden, z. B. Dawn in Chrome oder wgpu in Firefox. Werte ihn nie per Zeichenkettenvergleich aus. Unterscheide Fehler mit instanceof GPUValidationError, GPUOutOfMemoryError oder GPUInternalError.
Labels verwenden: Gibst du Ressourcen einen label, etwa bei createBuffer({ label: '…' }), erscheint dieser Name meist in der Meldung. Das macht die Fehlersuche deutlich leichter.
Kein Error-Objekt: GPUError erbt nicht von Error. Es hat daher kein stack, und es wird nicht geworfen. Mit try…catch fängst du es nicht ab.
Zeitversetzt: WebGPU-Fehler treten asynchron auf. popErrorScope() gibt ein Promise zurück. Liegt kein Fehler vor, erfüllt es sich mit null. Prüfe deshalb vor dem Zugriff auf message, ob überhaupt ein Fehler vorliegt.
Sicherheit: Gib die Meldung nicht ungefiltert per innerHTML aus. Sie kann Labels enthalten, die aus Nutzereingaben stammen. Verwende textContent.
Kompatibilität: WebGPU steht nur in sicheren Kontexten zur Verfügung, also HTTPS oder localhost. Prüfe vorher mit if (!navigator.gpu), ob es unterstützt wird.

Siehe auch

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