GPUInternalError — Schnittstelle · JavaScript-Referenz

Signatur

interface GPUInternalError extends GPUError

Beschreibung

GPUInternalError ist eine Unterklasse von GPUError aus der WebGPU API. Sie zeigt an, dass eine Operation fehlgeschlagen ist, obwohl der Aufruf gültig war – also alle Validierungsregeln der Spezifikation erfüllt hat. Die Ursache liegt im System oder in der Implementierung, typischerweise weil der Code die Grenzen der konkreten Hardware oder des Treibers überschreitet, und zwar auf eine Weise, die sich durch die gemeldeten limits und features nicht ausdrücken lässt.

Ein typisches Beispiel ist das Erzeugen einer Pipeline (createRenderPipeline(), createComputePipeline()), deren Shader für den Treiber zu komplex ist, etwa weil zu viele Register gebraucht werden oder der Shader-Compiler abbricht. Dieselbe Operation kann auf einem anderen Gerät problemlos funktionieren.

Solche Fehler fängt man über Fehlerbereiche ab: Mit device.pushErrorScope("internal") öffnet man einen Bereich, mit device.popErrorScope() schließt man ihn wieder und erhält ein Promise mit dem ersten aufgetretenen Fehler (oder null). Nicht abgefangene Fehler landen im Ereignis uncapturederror des GPUDevice. Eine Instanz lässt sich auch direkt per Konstruktor erzeugen, was vor allem für Tests oder zum Weiterleiten eigener Fehler nützlich ist.

Die Schnittstelle bringt keine eigenen Eigenschaften mit. Sie erbt message (eine menschenlesbare Fehlermeldung) von GPUError.

Parameter

Name	Typ	Default	Beschreibung
$message Pflicht	string		Nur beim Konstruktor `new GPUInternalError(message)`: menschenlesbare Beschreibung des Fehlers; wird als `message`-Eigenschaft verfügbar.

Rückgabewert

Typ

GPUInternalError

Beschreibung

Der Konstruktor gibt eine neue GPUInternalError-Instanz zurück. In der Praxis erhält man Instanzen meist über das Promise von GPUDevice.popErrorScope() oder über event.error im uncapturederror-Ereignis.

Beispiele

Interne Fehler bei der Pipeline-Erstellung abfangen

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

const shaderModule = device.createShaderModule({
  code: `
    @compute @workgroup_size(64)
    fn main(@builtin(global_invocation_id) id: vec3u) {
      // sehr komplexer Shader ...
    }
  `
});

device.pushErrorScope('internal');

const pipeline = device.createComputePipeline({
  layout: 'auto',
  compute: { module: shaderModule, entryPoint: 'main' }
});

const error = await device.popErrorScope();
if (error) {
  // error ist hier ein GPUInternalError
  console.error('Pipeline konnte nicht erstellt werden:', error.message);
  // z. B. auf eine einfachere Shader-Variante ausweichen
}

Bei Erfolg keine Ausgabe; sonst z. B. "Pipeline konnte nicht erstellt werden: ..."

Nicht abgefangene Fehler global unterscheiden

device.addEventListener('uncapturederror', (event) => {
  const { error } = event;
  if (error instanceof GPUInternalError) {
    console.warn('Interner GPU-Fehler (Hardware-/Treibergrenze):', error.message);
  } else if (error instanceof GPUValidationError) {
    console.error('Validierungsfehler im eigenen Code:', error.message);
  } else if (error instanceof GPUOutOfMemoryError) {
    console.error('Zu wenig GPU-Speicher:', error.message);
  }
});

Instanz direkt erzeugen (z. B. für Tests)

const err = new GPUInternalError('Shader zu komplex für diesen Treiber');

console.log(err instanceof GPUError);
console.log(err.message);

true Shader zu komplex für diesen Treiber

Mehrere Fehlerbereiche verschachteln

device.pushErrorScope('validation');
device.pushErrorScope('internal');

const pipeline = device.createRenderPipeline(pipelineDescriptor);

// Bereiche werden in umgekehrter Reihenfolge geschlossen (Stapel)
const internalError = await device.popErrorScope();
const validationError = await device.popErrorScope();

if (internalError) console.warn('Intern:', internalError.message);
if (validationError) console.error('Validierung:', validationError.message);

// Wichtig · Fallstricke

Nicht mit Validierungsfehlern verwechseln: Ein GPUInternalError bedeutet, dass der Aufruf gültig war. Er ist deshalb geräteabhängig und oft nicht reproduzierbar. Plane eine Ausweichlösung ein, etwa einfachere Shader oder kleinere Workgroups.
Filter muss passen: Ein Fehlerbereich mit pushErrorScope("validation") fängt keine internen Fehler ab. Nutze dafür den Filter "internal".
Asynchron: WebGPU meldet Fehler nicht per Exception, sondern asynchron. Ein try/catch um createComputePipeline() hilft hier nicht. Alternativ gibt createComputePipelineAsync() bzw. createRenderPipelineAsync() ein Promise zurück, das mit einem GPUPipelineError (reason: "internal") abgelehnt wird.
Fehlermeldungen: Inhalt und Format von message hängen von der Implementierung ab. Nicht für Programmlogik auswerten, nur zum Protokollieren verwenden.
Kompatibilität: WebGPU steht nur in sicheren Kontexten (HTTPS) und noch nicht in allen Browsern bzw. auf allen Plattformen zur Verfügung. Vorher mit if ('gpu' in navigator) prüfen. Auch Web Worker unterstützen die API.

Siehe auch

GPUExternalTexture GPUPipelineError GPUError GPUOutOfMemoryError GPUValidationError