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.

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:

• SynchronousStructChainingError 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.

Struct-Chaining Errors

A struct-chaining error happens when the SType of a struct in a struct chain is not valid for that chain.

Struct chains which are used in device-timeline validation/operations (e.g. WGPUBufferDescriptor in WGPUDeviceCreateBuffer) have their chain errors surfaced asynchronously, like any other validation error.

Out-Struct-Chain Error

Operations which take out-struct-chains (e.g. WGPULimits, in WGPUAdapterGetLimits/ WGPUDeviceGetLimits, but not in WGPUDeviceDescriptor) handle struct-chaining errors as follows:

• The output struct and struct chain is not modified.
• The operation produces a Synchronous Error (return value and log message).