{"record":{"id":"fdfd625f5ea7d037","repo":"bevyengine/bevy","slug":"failed-to-create-wgpu-surface","errorCode":null,"errorMessage":"Failed to create wgpu surface","messagePattern":"Failed to create wgpu surface","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"crates/bevy_render/src/renderer/mod.rs","lineNumber":253,"sourceCode":"    #[cfg(feature = \"raw_vulkan_init\")]\n    let instance = raw_vulkan_init::create_raw_vulkan_instance(\n        instance_descriptor,\n        &raw_vulkan_init_settings,\n        &mut additional_vulkan_features,\n    );\n\n    let surface = primary_window.and_then(|wrapper| {\n        let maybe_handle = wrapper\n            .0\n            .lock()\n            .expect(\"Couldn't get the window handle in time for renderer initialization\");\n        if let Some(wrapper) = maybe_handle.as_ref() {\n            // SAFETY: Plugins should be set up on the main thread.\n            let handle = unsafe { wrapper.get_handle() };\n            Some(\n                instance\n                    .create_surface(handle)\n                    .expect(\"Failed to create wgpu surface\"),\n            )\n        } else {\n            None\n        }\n    });\n\n    let force_fallback_adapter = std::env::var(\"WGPU_FORCE_FALLBACK_ADAPTER\")\n        .map_or(options.force_fallback_adapter, |v| {\n            !(v.is_empty() || v == \"0\" || v == \"false\")\n        });\n\n    let desired_adapter_name = std::env::var(\"WGPU_ADAPTER_NAME\")\n        .as_deref()\n        .map_or(options.adapter_name.clone(), |x| Some(x.to_lowercase()));\n\n    let request_adapter_options = RequestAdapterOptions {\n        power_preference: options.power_preference,\n        compatible_surface: surface.as_ref(),","sourceCodeStart":235,"sourceCodeEnd":271,"githubUrl":"https://github.com/bevyengine/bevy/blob/396ca727080776bd313bb892423b7d94e03b81b4/crates/bevy_render/src/renderer/mod.rs#L235-L271","documentation":"During RenderPlugin initialization Bevy creates the wgpu Surface for the primary window from its raw handle (via instance.create_surface) and expects success. Surface creation fails when the chosen wgpu instance/backends cannot present to that window — missing GPU drivers, a backend/display-server mismatch, or (on web) a canvas without a WebGPU/WebGL2 context.","triggerScenarios":"App::new() with a default primary window on a machine where the enabled wgpu backends cannot create a surface for it: no Vulkan/GL drivers, SSH session without X forwarding, Wayland/X11 mismatch, WGPU_BACKEND forcing an unsupported backend, or a browser canvas that fails context acquisition.","commonSituations":"Running on bare CI containers or remote servers without a display; forced WGPU_BACKEND=gl on a system without GLX/EGL; outdated GPU drivers on Windows/Linux; web builds targeting browsers without WebGL2.","solutions":["Install/verify GPU drivers and the required libraries (Vulkan loader, libx11/libwayland, EGL/GLX)","Set WGPU_BACKEND to a backend the machine actually supports (e.g. WGPU_BACKEND=gl on X11-less setups)","For headless rendering/CI/tests, run without a primary window: WindowPlugin { primary_window: None, ..default() } with Bevy's headless rendering support instead of a real surface","On web, confirm the canvas element exists and the browser supports WebGL2 or WebGPU"],"exampleFix":"// before (needs a real surface)\nApp::new().add_plugins(DefaultPlugins);\n\n// after (headless / CI)\nApp::new().add_plugins(\n    DefaultPlugins.set(WindowPlugin {\n        primary_window: None,\n        exit_condition: ExitCondition::DontExit,\n        ..default()\n    }),\n);","handlingStrategy":"fallback","validationCode":"// Before building the app, decide whether a real surface is possible:\nlet headless = std::env::var(\"CI\").is_ok() || std::env::var(\"DISPLAY\").is_err() && cfg!(target_os = \"linux\");\n// then choose WindowPlugin { primary_window: if headless { None } else { Some(Default::default()) }, ..default() }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep GPU drivers and Vulkan/GL system libraries installed on dev machines","Use headless rendering (primary_window: None) for CI and tests","Set WGPU_BACKEND explicitly when the default backend selection is wrong for the machine"],"tags":["bevy","wgpu","surface","gpu-drivers","windowing"],"backgroundTag":"surface-creation-failed","analyzedSha":"396ca727080776bd313bb892423b7d94e03b81b4","analyzedAt":"2026-08-20T16:12:39.808Z","contentChangedAt":"2026-08-20T16:12:39.808Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}