GPUDevice: pushErrorScope() method

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

Secure context: This feature is available only in secure contexts (HTTPS), in some or all supporting browsers.

Note: This feature is available in Web Workers.

The pushErrorScope() method of the GPUDevice interface pushes a new GPU error scope onto the device's error scope stack, allowing you to capture errors of a particular type.

Once you are done capturing errors, you can end capture by invoking GPUDevice.popErrorScope(). This pops the scope from the stack and returns a Promise that resolves to an object describing the first error captured in the scope, or null if no errors were captured.

Syntax

pushErrorScope(filter)

Parameters

filter

An enumerated value that specifies what type of error will be caught in this particular error scope. Possible values are:

"internal": The error scope will catch a GPUInternalError.
"out-of-memory": The error scope will catch a GPUOutOfMemoryError.
"validation": The error scope will catch a GPUValidationError.

Return value

None (Undefined).

Examples

The following example uses an error scope to capture a suspected validation error, logging it to the console.

device.pushErrorScope("validation");

let sampler = device.createSampler({
  maxAnisotropy: 0, // Invalid, maxAnisotropy must be at least 1.
});

device.popErrorScope().then((error) => {
  if (error) {
    sampler = null;
    console.error(`An error occurred while creating sampler: ${error.message}`);
  }
});

See WebGPU Error Handling best practices for a lot more examples and information.

Specifications

Specification
WebGPU # dom-gpudevice-pusherrorscope

Browser compatibility

BCD tables only load in the browser