Debugging

A grab bag of techniques for debugging wgpu when it misbehaves. The repo's wiki on GitHub has more depth on platform-specific tools (RenderDoc, Xcode GPU capture, PIX). This page focuses on what's available in the source tree.

InstanceFlags — your first stop

wgpu_types::InstanceFlags (defined in wgpu-types/src/instance.rs) controls the instance's debug behavior. They're set on the InstanceDescriptor or via environment variables.

Flag	Effect
DEBUG	Enable backend-specific debug layers (Vulkan validation layers, D3D12 debug layer, GL debug callback).
VALIDATION	Enable validation in those layers (Vulkan VVL, etc.).
GPU_BASED_VALIDATION	Enable GPU-based validation where supported (D3D12 GBV).
DISCARD_HAL_LABELS	Strip object labels before they reach the HAL (reduces overhead).
ALLOW_UNDERLYING_NONCOMPLIANT_ADAPTER	Surface adapters that don't fully comply with WebGPU.
AUTOMATIC_SHADER_FALLBACK	Allow naga to apply automatic conversions on shader failure.

InstanceFlags::from_env() and InstanceDescriptor::default() read the standard env-var set:

• WGPU_DEBUG=1
• WGPU_VALIDATION=1
• WGPU_GPU_BASED_VALIDATION=1
• WGPU_BACKEND=vulkan,metal,dx12,gl,noop
• WGPU_ADAPTER_NAME=...

The full list is in reference/configuration.md.

Logging

wgpu and wgpu-core use the log crate. wgpu-core/src/lib.rs defines the api_log!, api_log_debug!, and resource_log! macros, gated by features that promote them from trace/debug to info:

• enable feature api_log_info on wgpu-core to see every API call at info level.
• enable feature resource_log_info on wgpu-core to see resource lifecycle events at info level.

For ad-hoc debugging, set RUST_LOG:

RUST_LOG=wgpu_core=trace,wgpu_hal=info,naga=warn cargo run --bin wgpu-examples cube

Most examples (examples/features/src/main.rs) initialize env_logger for you.

RenderDoc capture

wgpu-hal/src/auxil/renderdoc.rs integrates with the RenderDoc in-application API on Vulkan, GL, and DX12. If RenderDoc is attached when wgpu starts, captures will work. Instance::generate_render_doc_capture (wgpu-hal/src/lib.rs) lets you start/stop captures programmatically. wgpu-info (wgpu-info/src/) reports whether RenderDoc is active.

Metal captures use MTLCaptureManager. wgpu-hal/src/metal/mod.rs calls into it; you can also start a capture from Xcode's GPU Frame Capture button while the app is running.

DX12 also supports PIX captures via the windows crate's PIX functions. Set WGPU_DX12_USE_PIX_MARKERS=1 to emit markers; PIX itself attaches externally.

Validation layers

• Vulkan: install the LunarG Vulkan SDK, set VK_LAYER_PATH and VK_INSTANCE_LAYERS=VK_LAYER_KHRONOS_validation (or set WGPU_VALIDATION=1 and let wgpu enable them). The SDK is required for the test suite.
• DX12: requires the Windows SDK. Set WGPU_DEBUG=1 and WGPU_VALIDATION=1. For GPU-based validation, also set WGPU_GPU_BASED_VALIDATION=1. cargo xtask install-warp (xtask/src/install_warp.rs) installs WARP for software DX12.
• Metal: enable the Metal validation layer via MTL_DEBUG_LAYER=1 in the environment.
• GL/GLES: WGPU_DEBUG=1 switches on the GL debug message callback. Output goes through the log crate.

Object labels and breadcrumbs

Most descriptors take a label: Label<'_> (Option<&str>). Labels propagate down to the HAL and into native APIs (vkSetDebugUtilsObjectNameEXT, MTLObject::setLabel, D3D12 SetName, GL glObjectLabel). Always set labels in real applications — they're free in release (DISCARD_HAL_LABELS) and invaluable in capture tools.

Tracing API calls

wgpu-core can record an on-disk trace of API calls (wgpu-core/src/device/trace.rs, wgpu-core/src/device/trace/). Enable the trace feature on wgpu-core; pass a directory in DeviceDescriptor::trace. The output can be replayed by the player crate (player/) for regression tests.

The trace format is documented inline in wgpu-core/src/device/trace.rs. The replay feature on wgpu-core is what player consumes.

The wgpu crate (the user-facing one) doesn't expose tracing; it's a wgpu-core-only feature, used by Firefox for crash repro.

Validating shaders out-of-band

Naga's CLI (naga-cli/) is the fastest way to inspect what naga sees:

naga my_shader.wgsl                     # parse + validate, print result
naga my_shader.wgsl my_shader.txt       # dump Naga IR
naga my_shader.wgsl my_shader.metal     # convert to MSL
naga my_shader.wgsl my_shader.spv       # convert to SPIR-V
naga my_shader.spv my_shader.txt --flow-dir flow-dir

For a particular wgpu run, set RUST_LOG=naga=debug to see the shader translation path; or extract the WGSL/SPIR-V module via a trace and feed it to naga.

Useful crates and tools in the workspace

• wgpu-info/ — adapter/device dump CLI: cargo run -p wgpu-info. Reports backends, features, limits, downlevel caps.
• lock-analyzer/ — offline analysis of wgpu-core's lock graph. Run on a build with the extra-recording feature.
• naga-cli/ — naga as a command-line tool.
• cts_runner/ — runs the WebGPU CTS via Deno; useful for reproducing CTS-specific failures.
• player/ — replays captured traces.
• xtask install-warp — installs the Microsoft WARP DLL for software DX12 testing.
• xtask install-agility-sdk — installs the D3D12 Agility SDK so tests use a recent runtime.

When a test "passes locally but fails in CI"

CI runs against software rasterizers (Mesa llvmpipe, WARP, sometimes SwiftShader). Your local hardware may compute slightly different floating-point results. The test framework's nv-flip image comparison has tolerance, but very different drivers can still produce different results. Steps:

• Reproduce locally with the same backend (e.g. install Mesa with LIBGL_ALWAYS_SOFTWARE=1 for GLES, cargo xtask install-warp for DX12 software).
• Check the test's TestParameters — if it's marked expects for some adapters, verify the expectation list (tests/src/expectations.rs).
• For naga snapshot diffs, regenerate snapshots locally and run cargo xtask validate <backend> to make sure the new output is actually valid.