new GPUInternalError() — Methode · JavaScript-Referenz

Signatur

new GPUInternalError(message)

Beschreibung

Der Konstruktor GPUInternalError() erzeugt ein Objekt vom Typ GPUInternalError. Dieses Interface erbt von GPUError. Normalerweise erzeugt der Browser solche Objekte selbst, zum Beispiel wenn eine Operation trotz korrekter Nutzung der API scheitert, weil ein Limit des Systems überschritten wird, das sich über GPUSupportedLimits nicht ausdrücken lässt. Ein typischer Fall ist ein zu komplexer Shader, den der Treiber nicht kompilieren kann.

Als Entwickler bekommst du einen GPUInternalError meist nicht über den Konstruktor, sondern auf einem von zwei Wegen:

über device.pushErrorScope("internal") und das Promise von device.popErrorScope(),
über das Ereignis uncapturederror am GPUDevice, und zwar als event.error.

Den Konstruktor selbst von Hand aufzurufen, lohnt sich vor allem in Tests und bei Mocks. Damit kannst du Fehlerbehandlung, Protokollierung oder die Anzeige für Nutzer prüfen, ohne dass tatsächlich ein interner GPU-Fehler auftritt. Die übergebene Nachricht steht anschließend in der schreibgeschützten Eigenschaft message.

Parameter

Name	Typ	Default	Beschreibung
$message Pflicht	string		Beschreibt, warum der Fehler aufgetreten ist. Der Text steht später in `error.message`.

Rückgabewert

Typ

GPUInternalError

Beschreibung

Ein neues GPUInternalError-Objekt, dessen message die übergebene Nachricht enthält.

Beispiele

Instanz erzeugen und prüfen

if ('GPUInternalError' in globalThis) {
  const err = new GPUInternalError('Shader zu komplex für den Treiber');
  console.log(err.message);
  console.log(err instanceof GPUError);
} else {
  console.log('WebGPU wird nicht unterstützt');
}

Shader zu komplex für den Treiber true

Interne Fehler über Error-Scopes abfangen

const adapter = await navigator.gpu?.requestAdapter();
if (!adapter) throw new Error('Kein GPU-Adapter verfügbar');
const device = await adapter.requestDevice();

device.pushErrorScope('internal');

const module = device.createShaderModule({
  code: `@compute @workgroup_size(64) fn main() {}`
});

const error = await device.popErrorScope();
if (error instanceof GPUInternalError) {
  console.warn('Interner GPU-Fehler:', error.message);
  // z. B. auf einfacheren Shader zurückfallen
} else {
  console.log('Shader erfolgreich erstellt');
}

Shader erfolgreich erstellt

Fehlerbehandlung mit selbst erzeugtem Fehler testen

const handleGpuError = (error) => {
  if (error instanceof GPUInternalError) return 'intern';
  if (error instanceof GPUValidationError) return 'validierung';
  if (error instanceof GPUOutOfMemoryError) return 'speicher';
  return 'unbekannt';
};

// Test ohne echte GPU-Operation
const fake = new GPUInternalError('Simulierter Treiberfehler');
console.log(handleGpuError(fake));

intern

Nicht abgefangene Fehler global protokollieren

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

device.addEventListener('uncapturederror', (event) => {
  if (event.error instanceof GPUInternalError) {
    console.error('Interner WebGPU-Fehler:', event.error.message);
  }
});

// Wichtig · Fallstricke

Kompatibilität: WebGPU ist noch nicht in allen Browsern und auf allen Plattformen verfügbar. Es funktioniert nur in sicheren Kontexten (HTTPS oder localhost). Prüfe die Unterstützung vorher mit 'gpu' in navigator oder 'GPUInternalError' in globalThis.
Ein selbst erzeugter GPUInternalError ist nur ein Datenobjekt. Er wird weder an das Gerät gemeldet noch löst er uncapturederror aus.
GPUError und damit auch GPUInternalError erben nicht von Error. Deshalb gibt es keinen stack, und err instanceof Error ergibt false. Wenn du einen solchen Fehler mit throw auslöst, verpacke ihn besser, zum Beispiel mit new Error(err.message, { cause: err }).
Interne Fehler können auch bei gültigem Code auftreten und hängen vom Gerät oder Treiber ab. Plane also Ausweichlösungen ein, etwa einfachere Shader oder kleinere Ressourcen.
Der Inhalt von message ist nicht standardisiert und unterscheidet sich je nach Browser. Verwende ihn nur zur Protokollierung und nicht für Programmlogik.

Siehe auch

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