{"record":{"id":"5d3372110ba17170","repo":"iced-rs/iced","slug":"create-surface","errorCode":null,"errorMessage":"Create surface","messagePattern":"Create surface","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"wgpu/src/window/compositor.rs","lineNumber":309,"sourceCode":"        }\n\n        Ok(new(settings, display, compatible_window, shell).await?)\n    }\n\n    fn create_renderer(&self, settings: renderer::Settings) -> Self::Renderer {\n        Renderer::new(self.engine.clone(), settings)\n    }\n\n    fn create_surface(\n        &mut self,\n        window: impl compositor::Window,\n        width: u32,\n        height: u32,\n    ) -> Self::Surface {\n        let mut surface = self\n            .instance\n            .create_surface(wgpu::SurfaceTarget::Window(Box::new(window)))\n            .expect(\"Create surface\");\n\n        if width > 0 && height > 0 {\n            self.configure_surface(&mut surface, width, height);\n        }\n\n        surface\n    }\n\n    fn configure_surface(&mut self, surface: &mut Self::Surface, width: u32, height: u32) {\n        surface.configure(\n            &self.engine.device,\n            &wgpu::SurfaceConfiguration {\n                usage: wgpu::TextureUsages::RENDER_ATTACHMENT,\n                format: self.format,\n                present_mode: self.settings.present_mode,\n                width,\n                height,\n                alpha_mode: self.alpha_mode,","sourceCodeStart":291,"sourceCodeEnd":327,"githubUrl":"https://github.com/iced-rs/iced/blob/d146509d893945de5c304cfaf4301335eee278bd/wgpu/src/window/compositor.rs#L291-L327","documentation":"The wgpu backend's compositor panics when wgpu cannot create a wgpu::Surface from the window's raw handle. Surface creation validates that the windowing system/platform combination is supported by the chosen wgpu backend; the expect treats unsupported surface targets as fatal since rendering cannot proceed.","triggerScenarios":"Calling create_surface with a window whose raw window/display handle is not supported by the active wgpu instance's backends (e.g. no Vulkan/GL/Metal available, Wayland/X11 mismatch, or an invalid handle).","commonSituations":"Running on a headless server or in a VM/container without GPU drivers; WGPU_BACKEND set to a backend that cannot present to the window; building wgpu without the needed platform feature; window destroyed/recreated concurrently with compositor setup.","solutions":["Verify GPU drivers are installed and usable (vulkaninfo/glxinfo work; on Linux try LIBGL_ALWAYS_SOFTWARE=1 for software rendering).","Set WGPU_BACKEND (e.g. vulkan,gl,metal) to a backend present on the machine.","Ensure the wgpu/iced versions match and platform windowing features are enabled in Cargo.toml.","Check the window handle is valid and the window is still alive when the surface is created.","Run under XWayland/X11 if the Wayland path is broken, or update wgpu for newer platform support."],"exampleFix":"// before (env)\ncargo run\n// after (env)\nWGPU_BACKEND=gl cargo run   # or WGPU_BACKEND=vulkan, depending on available drivers","handlingStrategy":"fallback","validationCode":"// shell check before launching the app\ncommand -v vulkaninfo && vulkaninfo --summary || echo \"no vulkan; try WGPU_BACKEND=gl\"","typeGuard":null,"tryCatchPattern":"// detect the failure early by probing adapter/surface compatibility before commit\n// (iced handles surface creation internally; validate the environment instead)\nlet adapter = pollster::block_on(instance.request_adapter(&wgpu::RequestAdapterOptions {\n    power_preference: wgpu::PowerPreference::default(),\n    compatible_surface: None,\n    force_fallback_adapter: false,\n}));\nif adapter.is_none() { eprintln!(\"No compatible GPU backend; set WGPU_BACKEND or install drivers\"); }","preventionTips":["Verify GPU drivers/backends exist on target machines before deploying.","Set WGPU_BACKEND explicitly in constrained environments.","Test GUI startup under xvfb in CI instead of calling run() headless.","Keep wgpu/iced versions matched."],"tags":["wgpu","graphics","surface","platform","panic"],"backgroundTag":"unsupported-platform","analyzedSha":"d146509d893945de5c304cfaf4301335eee278bd","analyzedAt":"2026-09-11T16:54:14.229Z","contentChangedAt":"2026-09-11T16:54:14.229Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}