{"record":{"id":"5f360ff0c54548e6","repo":"gfx-rs/wgpu","slug":"wgpu-adapter-name-set-but-no-matching-adapter-foun","errorCode":null,"errorMessage":"WGPU_ADAPTER_NAME set but no matching adapter found!","messagePattern":"WGPU_ADAPTER_NAME set but no matching adapter found!","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"wgpu/src/util/init.rs","lineNumber":44,"sourceCode":"    let adapters = instance.enumerate_adapters(crate::Backends::all()).await;\n\n    let mut chosen_adapter = None;\n    for adapter in adapters {\n        let info = adapter.get_info();\n\n        if let Some(surface) = compatible_surface {\n            if !adapter.is_surface_supported(surface) {\n                continue;\n            }\n        }\n\n        if info.name.to_lowercase().contains(&desired_adapter_name) {\n            chosen_adapter = Some(adapter);\n            break;\n        }\n    }\n\n    Ok(chosen_adapter.expect(\"WGPU_ADAPTER_NAME set but no matching adapter found!\"))\n}\n\n/// Initialize the adapter obeying the `WGPU_ADAPTER_NAME` environment variable.\n#[cfg(not(wgpu_core))]\npub async fn initialize_adapter_from_env(\n    _instance: &Instance,\n    _compatible_surface: Option<&Surface<'_>>,\n) -> Result<Adapter, wgt::RequestAdapterError> {\n    Err(wgt::RequestAdapterError::EnvNotSet)\n}\n\n/// Initialize the adapter obeying the `WGPU_ADAPTER_NAME` environment variable and if it doesn't exist fall back on a default adapter.\npub async fn initialize_adapter_from_env_or_default(\n    instance: &Instance,\n    compatible_surface: Option<&Surface<'_>>,\n) -> Result<Adapter, wgt::RequestAdapterError> {\n    match initialize_adapter_from_env(instance, compatible_surface).await {\n        Ok(a) => Ok(a),","sourceCodeStart":26,"sourceCodeEnd":62,"githubUrl":"https://github.com/gfx-rs/wgpu/blob/3e11ff59bf3f9795d285ecc045014089640d7248/wgpu/src/util/init.rs#L26-L62","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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","Set a short vendor substring like \"nvidia\", \"amd\", or \"intel\" instead of a full model string","Unset WGPU_ADAPTER_NAME to fall back to the default adapter selection","Enable the required backend features at compile time (e.g. the \"vulkan\" feature) so the adapter is actually enumerated","Use explicit request_adapter options (power_preference/backends) in code instead of the env var"],"exampleFix":"// before (env)\n# WGPU_ADAPTER_NAME=\"NVIDIA GeForce RTX 4090 Ti\"\n// after\n# WGPU_ADAPTER_NAME=\"nvidia\"   // substring, case-insensitive\n// or unset entirely and select in code:\nlet adapter = instance\n    .request_adapter(&RequestAdapterOptions {\n        power_preference: PowerPreference::HighPerformance,\n        ..Default::default()\n    })\n    .expect(\"no suitable adapter\");","handlingStrategy":"validation","validationCode":"// Verify the env var matches an enumerated adapter before initializing:\nif let Ok(desired) = std::env::var(\"WGPU_ADAPTER_NAME\") {\n    let desired = desired.to_lowercase();\n    let adapters = instance.enumerate_adapters(wgt::Backends::all());\n    let matched: Vec<_> = adapters.iter()\n        .filter(|a| a.get_info().name.to_lowercase().contains(&desired))\n        .collect();\n    if matched.is_empty() {\n        eprintln!(\"WGPU_ADAPTER_NAME={desired:?} matches none of:\");\n        for a in &adapters {\n            eprintln!(\"  {}\", a.get_info().name);\n        }\n        std::process::exit(1);\n    }\n}","typeGuard":"fn adapter_name_env_valid(instance: &Instance) -> bool {\n    match std::env::var(\"WGPU_ADAPTER_NAME\") {\n        Err(_) => true,\n        Ok(name) => {\n            let name = name.to_lowercase();\n            instance.enumerate_adapters(wgt::Backends::all()).iter()\n                .any(|a| a.get_info().name.to_lowercase().contains(&name))\n        }\n    }\n}","tryCatchPattern":"// The library panics via expect, so it cannot be caught as an error.\n// Fall back to default selection yourself before calling the helper:\nlet adapter = if adapter_name_env_valid(&instance) {\n    initialize_adapter_from_env(&instance, Backends::all()).await\n} else {\n    instance\n        .request_adapter(&RequestAdapterOptions::default())\n        .await\n        .expect(\"no adapter available\")\n};","preventionTips":["Set WGPU_ADAPTER_NAME to a short vendor substring (\"nvidia\", \"amd\", \"intel\"), never a full model string","Log enumerate_adapters().map(|a| a.get_info().name) at startup to see valid names","Unset the variable in CI/containers where GPU presence is unknown","Ensure the backend feature (vulkan/metal/gl) for the target adapter is compiled in","Prefer programmatic RequestAdapterOptions over env-var selection for portable apps"],"tags":["webgpu","adapter-selection","env-var","panic","configuration"],"backgroundTag":"adapter-not-found","analyzedSha":"3e11ff59bf3f9795d285ecc045014089640d7248","analyzedAt":"2026-09-03T01:43:21.459Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-10T07:17:11.731Z"}