gfx-rs/wgpu · error

Earlier check of `enabled_backend_features` should have prev

Error message

Earlier check of `enabled_backend_features` should have prevented getting here!

What it means

`Instance::new` in the wgpu crate enumerates compiled-in backends (Vulkan, Metal, DX12, GL, WebGPU) and creates the first available one. If no backend was compiled in or all backends failed to initialize, this final unreachable! fires — it is supposed to be prevented by an earlier check of `enabled_backend_features`, so hitting it indicates either a no-backend build or a wgpu bug.

Source

Thrown at wgpu/src/api/instance.rs:100

            if is_only_available_backend || (requested_webgpu && support_webgpu) {
                return Self {
                    inner: crate::backend::ContextWebGpu::new(desc).into(),
                };
            }
        }

        #[cfg(wgpu_core)]
        {
            return Self {
                inner: crate::backend::ContextWgpuCore::new(desc).into(),
            };
        }

        // Silence unused variable warnings without adding _ to the parameter name (which shows up in docs).
        let _ = desc;

        unreachable!(
            "Earlier check of `enabled_backend_features` should have prevented getting here!"
        );
    }

    /// Returns which backends can be picked for the current build configuration.
    ///
    /// The returned set depends on a combination of target platform and enabled features.
    /// This does *not* do any runtime checks and is exclusively based on compile time information.
    ///
    /// `InstanceDescriptor::backends` does not need to be a subset of this,
    /// but any backend that is not in this set, will not be picked.
    pub const fn enabled_backend_features() -> Backends {
        let mut backends = Backends::empty();
        // `.set` and `|=` don't work in a `const` context.
        if cfg!(noop) {
            backends = backends.union(Backends::NOOP);
        }
        if cfg!(vulkan) {

View on GitHub (pinned to 3e11ff59bf)

Solutions

1. Enable at least one backend feature in Cargo.toml, e.g. `wgpu = { version = "...", features = ["vulkan"] }` or restore `default-features = false, features = ["wgsl", "vulkan", "metal", "dx12", "gl"]`
2. Check the target platform supports an enabled backend and that runtime prerequisites (drivers, Vulkan loader) are present
3. Call `Instance::enabled_backends()` / check available backends before creating an instance and handle the empty case gracefully
4. Update wgpu — if backends are enabled and available yet this still fires, it is a bug; file an issue

Example fix

// before
wgpu = { version = "26", default-features = false, features = ["wgsl"] } // no backend
// after
wgpu = { version = "26", default-features = false, features = ["wgsl", "vulkan"] }

let backends = Instance::enabled_backends();
if backends.is_empty() {
    eprintln!("no wgpu backend compiled in — enable a backend cargo feature");
    std::process::exit(1);
}

fn has_backend() -> bool {
    !wgpu::Instance::enabled_backends().is_empty()
}

When it happens

Trigger: Calling `Instance::new(&desc)` in a build where no graphics backend feature is enabled (or all enabled backends fail their runtime guards), so backend enumeration falls through to the terminal unreachable!.

Common situations: Building for a platform/target with all backend cargo features disabled; compiling with `default-features = false` and forgetting to add a backend feature; WebGPU builds where the browser environment lacks WebGPU but backends were filtered out earlier than expected.

Related errors

• No context available. You need to enable one of wgpu's backe
• wgpu error: {err}
• Mismatched pop_error_scope call: no error scope for this thr
• Mismatched pop_error_scope call: error scopes must be popped
• ${name} is not webgpu

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