gfx-rs/wgpu · error

WGPU_ADAPTER_NAME set but no matching adapter found!

Error message

WGPU_ADAPTER_NAME set but no matching adapter found!

What it means

When the WGPU_ADAPTER_NAME environment variable is set, initialize_adapter_from_env enumerates all available adapters and picks the first whose name contains the given substring (case-insensitively). This panic fires when the variable is set but none of the enumerated adapters matched, so no adapter could be selected for you.

Source

Thrown at wgpu/src/util/init.rs:44

    let adapters = instance.enumerate_adapters(crate::Backends::all()).await;

    let mut chosen_adapter = None;
    for adapter in adapters {
        let info = adapter.get_info();

        if let Some(surface) = compatible_surface {
            if !adapter.is_surface_supported(surface) {
                continue;
            }
        }

        if info.name.to_lowercase().contains(&desired_adapter_name) {
            chosen_adapter = Some(adapter);
            break;
        }
    }

    Ok(chosen_adapter.expect("WGPU_ADAPTER_NAME set but no matching adapter found!"))
}

/// Initialize the adapter obeying the `WGPU_ADAPTER_NAME` environment variable.
#[cfg(not(wgpu_core))]
pub async fn initialize_adapter_from_env(
    _instance: &Instance,
    _compatible_surface: Option<&Surface<'_>>,
) -> Result<Adapter, wgt::RequestAdapterError> {
    Err(wgt::RequestAdapterError::EnvNotSet)
}

/// Initialize the adapter obeying the `WGPU_ADAPTER_NAME` environment variable and if it doesn't exist fall back on a default adapter.
pub async fn initialize_adapter_from_env_or_default(
    instance: &Instance,
    compatible_surface: Option<&Surface<'_>>,
) -> Result<Adapter, wgt::RequestAdapterError> {
    match initialize_adapter_from_env(instance, compatible_surface).await {
        Ok(a) => Ok(a),

View on GitHub (pinned to 3e11ff59bf)

Solutions

1. Print instance.enumerate_adapters(AdapterOptions::default()) (or instance.request_adapter) and their info().name, then set WGPU_ADAPTER_NAME to a substring that actually appears
2. Set a short vendor substring like "nvidia", "amd", or "intel" instead of a full model string
3. Unset WGPU_ADAPTER_NAME to fall back to the default adapter selection
4. Enable the required backend features at compile time (e.g. the "vulkan" feature) so the adapter is actually enumerated
5. Use explicit request_adapter options (power_preference/backends) in code instead of the env var

Example fix

// before (env)
# WGPU_ADAPTER_NAME="NVIDIA GeForce RTX 4090 Ti"
// after
# WGPU_ADAPTER_NAME="nvidia"   // substring, case-insensitive
// or unset entirely and select in code:
let adapter = instance
    .request_adapter(&RequestAdapterOptions {
        power_preference: PowerPreference::HighPerformance,
        ..Default::default()
    })
    .expect("no suitable adapter");

// Verify the env var matches an enumerated adapter before initializing:
if let Ok(desired) = std::env::var("WGPU_ADAPTER_NAME") {
    let desired = desired.to_lowercase();
    let adapters = instance.enumerate_adapters(wgt::Backends::all());
    let matched: Vec<_> = adapters.iter()
        .filter(|a| a.get_info().name.to_lowercase().contains(&desired))
        .collect();
    if matched.is_empty() {
        eprintln!("WGPU_ADAPTER_NAME={desired:?} matches none of:");
        for a in &adapters {
            eprintln!("  {}", a.get_info().name);
        }
        std::process::exit(1);
    }
}

fn adapter_name_env_valid(instance: &Instance) -> bool {
    match std::env::var("WGPU_ADAPTER_NAME") {
        Err(_) => true,
        Ok(name) => {
            let name = name.to_lowercase();
            instance.enumerate_adapters(wgt::Backends::all()).iter()
                .any(|a| a.get_info().name.to_lowercase().contains(&name))
        }
    }
}

// The library panics via expect, so it cannot be caught as an error.
// Fall back to default selection yourself before calling the helper:
let adapter = if adapter_name_env_valid(&instance) {
    initialize_adapter_from_env(&instance, Backends::all()).await
} else {
    instance
        .request_adapter(&RequestAdapterOptions::default())
        .await
        .expect("no adapter available")
};

When it happens

Trigger: WGPU_ADAPTER_NAME contains a name that no installed adapter matches: a misspelled vendor/model (e.g. "NVIDA", "RTX 4090Ti"), a device not present on the current machine, a remote/CI machine with a software adapter only, or a backend (vulkan/metal/gl) disabled at compile time that would have exposed the adapter.

Common situations: Copy-pasting an adapter name from a dev machine to CI or another user's machine; env var left set in a container/VM with different GPUs; expecting a full exact model string match when matching is substring-based against a differently formatted name; running a wasm build where native adapters don't exist.

Related errors

• No wgpu backend feature that is implemented for the target p
• Unexpected error: constructor={constructor} value={value}
• {:?} is not enabled for this backend
• VERTEX_ATTRIBUTE_64BIT feature must be enabled to use Double
• Mismatched pop_error_scope call: error scopes must be popped

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