What causes "not implemented" in gfx-rs/wgpu?

Do not use RayPayload/IncomingRayPayload globals in shaders translated to Metal; restructure to pass payload data via storage buffers.

gfx-rs/wgpu · error

not implemented

Error message

not implemented

What it means

This is a Rust `unimplemented!()` panic raised by naga's Metal (MSL) backend in `needs_access_qualifier`, which decides whether a global variable's address space needs an access qualifier in generated MSL. The MSL writer does not yet know how to classify the `RayPayload` or `IncomingRayPayload` address spaces, so encountering a module whose globals use them panics instead of producing Metal code. It is a capability gap in the backend, not a user error in the shader itself being validated.

Source

Thrown at naga/src/back/msl/writer.rs:669

            | Self::WorkGroup
            | Self::Immediate
            | Self::Handle
            | Self::TaskPayload => true,
            Self::Function => false,
            Self::RayPayload | Self::IncomingRayPayload => unreachable!(),
        }
    }

    /// Returns true if the address space may need a "const" qualifier.
    const fn needs_access_qualifier(&self) -> bool {
        match *self {
            //Note: we are ignoring the storage access here, and instead
            // rely on the actual use of a global by functions. This means we
            // may end up with "const" even if the binding is read-write,
            // and that should be OK.
            Self::Storage { .. } => true,
            Self::TaskPayload => true,
            Self::RayPayload | Self::IncomingRayPayload => unimplemented!(),
            // These should always be read-write.
            Self::Private | Self::WorkGroup => false,
            // These translate to `constant` address space, no need for qualifiers.
            Self::Uniform | Self::Immediate => false,
            // Not applicable.
            Self::Handle | Self::Function => false,
        }
    }

    const fn to_msl_name(self) -> Option<&'static str> {
        match self {
            Self::Handle => None,
            Self::Uniform | Self::Immediate => Some("constant"),
            Self::Storage { .. } => Some("device"),
            // note for `RayPayload`, this probably needs to be emulated as a
            // private variable, as metal has essentially an inout input
            // for where it is passed.
            Self::Private | Self::Function | Self::RayPayload => Some("thread"),

View on GitHub (pinned to 3e11ff59bf)

Solutions

Do not use RayPayload/IncomingRayPayload globals in shaders translated to Metal; restructure to pass payload data via storage buffers.
Check naga's issue tracker/CHANGELOG for MSL ray tracing support status and upgrade naga once implemented.
Detect ray payload address space usage before calling the MSL writer and reject the module with a clear error instead of panicking.

Example fix

// before: module with
global_var: var<ray_payload> Payload p;
// after (Metal-safe workaround)
global_var: var<storage, read_write> Payload p;

Defensive patterns

Strategy: validation

Validate before calling

fn uses_ray_payload(module: &naga::Module) -> bool {
    module.global_variables.iter().any(|(_, v)|
        matches!(v.space, naga::AddressSpace::RayPayload | naga::AddressSpace::IncomingRayPayload))
}
// reject before calling the MSL writer

Type guard

fn is_ray_payload(space: &naga::AddressSpace) -> bool {
    matches!(space, naga::AddressSpace::RayPayload | naga::AddressSpace::IncomingRayPayload)
}

Try / catch

// panics are not catchable in Rust; isolate translation in a subprocess or catch_unwind
let result = std::panic::catch_unwind(|| naga::msl::write_string(...));

Prevention

Pre-scan naga IR for ray tracing address spaces before targeting MSL
Keep naga updated on MSL ray tracing support status
Use catch_unwind or process isolation around backend translation in production pipelines

When it happens

Trigger: Translating a WGSL/SPIR-V module to MSL whose global variables are declared in the `AddressSpace::RayPayload` or `AddressSpace::IncomingRayPayload` address spaces (i.e. any shader using ray tracing payloads), when the code path asks for an access qualifier for that global.

Common situations: Developers experimenting with naga's in-progress ray tracing support and targeting Metal; cross-compiling a ray tracing shader that works on a backend with ray payload support (e.g. SPIR-V) down to MSL; enabling ray tracing IR types before the MSL backend caught up.

Related errors

AI-assisted analysis of gfx-rs/wgpu@3e11ff59bf (2026-09-03). Data as JSON: /api/errors/eeabacb6370435db. Report an issue: GitHub.