What causes "metal does not support vertex ray hit return" in gfx-rs/wgpu?

Move the ray query to a fragment/compute stage where vertex_return is false

metal does not support vertex ray hit return

Error message

metal does not support vertex ray hit return

What it means

The MSL writer panics when translating an `AccelerationStructure` type declared with `vertex_return: true`, because Metal's ray tracing does not support returning ray hits from the vertex stage. This is an explicit unsupported-feature guard in naga's Metal backend.

Source

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

                        ("texture", "", format.into(), access)
                    }
                    crate::ImageClass::External => {
                        return write!(out, "{EXTERNAL_TEXTURE_WRAPPER_STRUCT}");
                    }
                };
                let base_name = scalar.to_msl_name();
                let array_str = if arrayed { "_array" } else { "" };
                write!(
                    out,
                    "{NAMESPACE}::{texture_str}{dim_str}{msaa_str}{array_str}<{base_name}, {NAMESPACE}::access::{access}>",
                )
            }
            crate::TypeInner::Sampler { comparison: _ } => {
                write!(out, "{NAMESPACE}::sampler")
            }
            crate::TypeInner::AccelerationStructure { vertex_return } => {
                if vertex_return {
                    unimplemented!("metal does not support vertex ray hit return")
                }
                write!(out, "{RT_NAMESPACE}::instance_acceleration_structure")
            }
            crate::TypeInner::RayQuery { vertex_return } => {
                if vertex_return {
                    unimplemented!("metal does not support vertex ray hit return")
                }
                write!(out, "{}", super::ray::metal_intersector_ty())
            }
            crate::TypeInner::BindingArray { base, .. } => {
                let base_inner = &self.gctx.types[base].inner;
                let base_tyname = Self {
                    handle: base,
                    first_time: false,
                    ..*self
                };
                match *base_inner {
                    crate::TypeInner::Struct { .. } => {

View on GitHub (pinned to 3e11ff59bf)

Solutions

Move the ray query to a fragment/compute stage where vertex_return is false
Rebuild the shader/IR so acceleration structure and ray query types use vertex_return: false (drop the vertex ray hit return capability)
Use a backend with vertex ray tracing support (Vulkan/DX12 with appropriate extensions) for this shader

Example fix

// before (naga IR)
TypeInner::AccelerationStructure { vertex_return: true }
// after
TypeInner::AccelerationStructure { vertex_return: false } // run ray query from fragment/compute stage

Defensive patterns

Strategy: fallback

Try / catch

// compile the shader per-backend at startup; if MSL translation panics/fails, disable ray tracing on Metal

Prevention

Never enable vertex_return on acceleration structures for Metal targets
Keep ray queries in fragment or compute stages
Gate ray tracing features per adapter backend at runtime
Compile shaders for all target backends in CI to surface unimplemented paths early

When it happens

Trigger: Compiling a shader for Metal that declares an acceleration structure binding or type with vertex return enabled (ray hit data returned from vertex-stage ray queries), e.g. via `acceleration_structure` with vertex_return in WGSL extensions or naga IR built with `VertexReturnValue` capability.

Common situations: Ray tracing on Apple GPUs where a shader attempts vertex-stage ray hit extraction; porting a DXR/Vulkan ray tracing shader that queries intersections in the vertex shader over to Metal via naga/wgpu.

Related errors

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