new GPUValidationError() — Methode · JavaScript-Referenz

Signatur

new GPUValidationError(message)

Beschreibung

Der Konstruktor GPUValidationError() erzeugt eine neue Instanz von GPUValidationError. Diese Klasse erbt von GPUError und steht für Fehler, die bei der Validierung von WebGPU-Aufrufen entstehen, zum Beispiel wenn ein Puffer mit ungültigen Verwendungsflags angelegt wird, ein Shader nicht kompiliert oder eine Bind-Group nicht zum Pipeline-Layout passt.

Im normalen Anwendungscode ruft man den Konstruktor selten direkt auf. Validierungsfehler erzeugt der Browser selbst und liefert sie über GPUDevice.popErrorScope() (nachdem mit pushErrorScope("validation") ein Fehlerbereich geöffnet wurde) oder über das Ereignis uncapturederror des Geräts aus. Sinnvoll ist der direkte Aufruf vor allem für Tests, Mocks und Polyfills, wenn man eigene Fehlerbehandlung prüfen will, ohne echte GPU-Fehler auslösen zu müssen.

Das erzeugte Objekt hat nur die geerbte, schreibgeschützte Eigenschaft message. Mit instanceof GPUValidationError lassen sich Validierungsfehler von GPUOutOfMemoryError und GPUInternalError unterscheiden.

Parameter

Name	Typ	Default	Beschreibung
$message Pflicht	string		Lesbare Beschreibung des Fehlers, die später über `error.message` abrufbar ist.

Rückgabewert

Typ

GPUValidationError

Beschreibung

Eine neue GPUValidationError-Instanz, deren Eigenschaft message den übergebenen Text enthält.

Beispiele

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

if ('GPUValidationError' in globalThis) {
  const err = new GPUValidationError('Pufferverwendung ist ungültig');
  console.log(err.message);
  console.log(err instanceof GPUError);
} else {
  console.log('WebGPU wird nicht unterstützt');
}

Pufferverwendung ist ungültig true

Echten Validierungsfehler über einen Fehlerbereich abfangen

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

device.pushErrorScope('validation');

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

const error = await device.popErrorScope();
if (error instanceof GPUValidationError) {
  console.warn('Validierungsfehler:', error.message);
}

Validierungsfehler: (browserabhängige Meldung zur ungültigen Buffer-Usage)

Fehlerbehandlung mit einem gemockten Fehler testen

const describeGpuError = (error) => {
  if (error instanceof GPUValidationError) return `Validierung: ${error.message}`;
  if (error instanceof GPUOutOfMemoryError) return `Speicher: ${error.message}`;
  if (error instanceof GPUInternalError) return `Intern: ${error.message}`;
  return 'Kein Fehler';
};

console.log(describeGpuError(new GPUValidationError('Bind-Group passt nicht zum Layout')));
console.log(describeGpuError(null));

Validierung: Bind-Group passt nicht zum Layout Kein Fehler

Nicht abgefangene Fehler global protokollieren

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

device.addEventListener('uncapturederror', (event) => {
  if (event.error instanceof GPUValidationError) {
    console.error('WebGPU-Validierung fehlgeschlagen:', event.error.message);
  }
});

// Ungültiges WGSL löst einen Validierungsfehler aus
device.createShaderModule({ code: 'das ist kein WGSL' });

WebGPU-Validierung fehlgeschlagen: (Shader-Kompilierungsfehler, browserabhängig)

// Wichtig · Fallstricke

Kein throw: WebGPU-Methoden wie createBuffer() werfen bei Validierungsfehlern keine Ausnahme. Der Fehler wird asynchron gemeldet, entweder über popErrorScope() oder über uncapturederror. Ein try…catch um den Aufruf hilft also nicht.
Kein Error-Objekt: GPUValidationError erbt nicht von Error. Deshalb gibt es keinen stack, und instanceof Error liefert false.
Der Parameter message ist Pflicht. Ein Aufruf ohne Argument erzeugt je nach Engine einen TypeError oder die Meldung "undefined". Außerdem funktioniert der Konstruktor nur mit new.
Die Texte der vom Browser erzeugten Meldungen sind nicht standardisiert und unterscheiden sich zwischen Implementierungen. Sie eignen sich zur Fehlersuche, aber nicht für String-Vergleiche in der Programmlogik.
Kompatibilität: WebGPU ist nur in sicheren Kontexten (HTTPS) und in neueren Browsern verfügbar. Prüfe vorher mit 'gpu' in navigator bzw. 'GPUValidationError' in globalThis, ob die Schnittstelle vorhanden ist. In Node.js gibt es die Schnittstelle nicht ohne Zusatzpakete wie Dawn-Bindings.

Siehe auch

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