iced-rs/iced · critical

Create surface

Error message

Create surface

What it means

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.

Solutions

1. Verify GPU drivers are installed and usable (vulkaninfo/glxinfo work; on Linux try LIBGL_ALWAYS_SOFTWARE=1 for software rendering).
2. Set WGPU_BACKEND (e.g. vulkan,gl,metal) to a backend present on the machine.
3. Ensure the wgpu/iced versions match and platform windowing features are enabled in Cargo.toml.
4. Check the window handle is valid and the window is still alive when the surface is created.
5. Run under XWayland/X11 if the Wayland path is broken, or update wgpu for newer platform support.

Example fix

// before (env)
cargo run
// after (env)
WGPU_BACKEND=gl cargo run   # or WGPU_BACKEND=vulkan, depending on available drivers

// shell check before launching the app
command -v vulkaninfo && vulkaninfo --summary || echo "no vulkan; try WGPU_BACKEND=gl"

// detect the failure early by probing adapter/surface compatibility before commit
// (iced handles surface creation internally; validate the environment instead)
let adapter = pollster::block_on(instance.request_adapter(&wgpu::RequestAdapterOptions {
    power_preference: wgpu::PowerPreference::default(),
    compatible_surface: None,
    force_fallback_adapter: false,
}));
if adapter.is_none() { eprintln!("No compatible GPU backend; set WGPU_BACKEND or install drivers"); }

When it happens

Trigger: 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).

Common situations: 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.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

• {error:?}
• Create softbuffer context
• Create window
• Fill rectangle
• Resize surface

AI-assisted analysis of iced-rs/iced@d146509d89 (2026-09-11). Data as JSON: /api/errors/5d3372110ba17170. Report an issue: GitHub.

Appendix: source

Thrown at wgpu/src/window/compositor.rs:309

        }

        Ok(new(settings, display, compatible_window, shell).await?)
    }

    fn create_renderer(&self, settings: renderer::Settings) -> Self::Renderer {
        Renderer::new(self.engine.clone(), settings)
    }

    fn create_surface(
        &mut self,
        window: impl compositor::Window,
        width: u32,
        height: u32,
    ) -> Self::Surface {
        let mut surface = self
            .instance
            .create_surface(wgpu::SurfaceTarget::Window(Box::new(window)))
            .expect("Create surface");

        if width > 0 && height > 0 {
            self.configure_surface(&mut surface, width, height);
        }

        surface
    }

    fn configure_surface(&mut self, surface: &mut Self::Surface, width: u32, height: u32) {
        surface.configure(
            &self.engine.device,
            &wgpu::SurfaceConfiguration {
                usage: wgpu::TextureUsages::RENDER_ATTACHMENT,
                format: self.format,
                present_mode: self.settings.present_mode,
                width,
                height,
                alpha_mode: self.alpha_mode,

View on GitHub (pinned to d146509d89)