Errors

Errors are surfaced in several ways.

Most errors only result from incorrect use of the API and should not need to be handled at runtime. However, a few (WGPUErrorType_OutOfMemory, WGPUErrorType_Internal) are potentially useful to handle.

Device Error

These behave the same way as in the WebGPU JavaScript API specification. They are receivable via wgpuDevicePopErrorScope() and WGPUDeviceDescriptor::uncapturedErrorCallbackInfo.

These errors include:

• All device-timeline errors in the WebGPU specification.
• Enum values which are numerically invalid (this is not possible in JavaScript).
• Enum values which are require features not enabled on the device (a content-timeline error in JavaScript), for example compressed texture formats.
• Other content-timeline errors where specified.
• Non-Finite Float Value Errors (except when they interrupt Wasm execution)

Error Scopes

Error scopes are used via wgpuDevicePushErrorScope, wgpuDevicePopErrorScope, and WGPUDeviceDescriptor::uncapturedErrorCallbackInfo. These behave the same as in the JavaScript API, except for considerations around multi-threading (which JavaScript doesn't have at the time of this writing):

• The error scope stack state is thread-local: each thread has a separate stack, which is initially empty. The error scope that captures an error depends on which thread made the API call that generated the error. Note in particular:
  • Async callbacks run on various threads and with unpredictable timing (see Asynchronous Operations), except when using wgpuInstanceWaitAny. To avoid race conditions, if error scopes are used, applications generally should avoid having device errors escape from an async function, and/or should not keep scopes open when callbacks that could produce errors may run.
  • Runtimes with async task support (I/O runtimes, language async/coroutines/futures, etc.) may use "green threads" style systems to schedule tasks on different OS threads. Error scope stack state is OS-thread-local, not green-thread-local.
• The UncapturedError callback (WGPUDeviceDescriptor::uncapturedErrorCallbackInfo) is called for uncaptured errors on all threads. It may be called inline inside of a call to the API.

Callback Error

These behave similarly to the Promise-returning JavaScript APIs. Instead of there being two callbacks like in JavaScript (one for resolve and one for reject), there is a single callback which receives a status code, and depending on the status, either a valid result with an empty message string ({NULL, 0}), or an invalid result with a non-empty message string.

Synchronous Error

These errors include:

• Out-Struct-Chain Error cases.
• Content-timeline errors other than those which are surfaced as Device Error in webgpu.h. See specific documentation to determine how each error is exposed.

Generally these will return some kind of failure status (like WGPUStatus_Error) or NULL, and produce an Implementation-Defined Logging message.

Implementation-Defined Logging

Entry points may also specify that they produce "implementation-defined logging". These messages are logged in an implementation defined way (e.g. to an implementation-specific callback, or to a logging runtime). They are intended to be intended to be read by humans, useful primarily for development and crash reporting.