{"record":{"id":"3c8f90a25805d8a8","repo":"iced-rs/iced","slug":"create-softbuffer-surface-for-window","errorCode":null,"errorMessage":"Create softbuffer surface for window","messagePattern":"Create softbuffer surface for window","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"tiny_skia/src/window/compositor.rs","lineNumber":62,"sourceCode":"                },\n            });\n        }\n\n        Ok(new(display))\n    }\n\n    fn create_renderer(&self, settings: renderer::Settings) -> Self::Renderer {\n        Renderer::new(settings)\n    }\n\n    fn create_surface(\n        &mut self,\n        window: impl compositor::Window + Clone,\n        width: u32,\n        height: u32,\n    ) -> Self::Surface {\n        let window = softbuffer::Surface::new(&self.context, Box::new(window.clone()) as _)\n            .expect(\"Create softbuffer surface for window\");\n\n        let mut surface = Surface {\n            window,\n            clip_mask: tiny_skia::Mask::new(1, 1).expect(\"Create clip mask\"),\n            frames: VecDeque::new(),\n            max_age: 0,\n        };\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\n            .window","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/iced-rs/iced/blob/3de451447bd28217bb535632867550908e29d5d0/tiny_skia/src/window/compositor.rs#L44-L80","documentation":"iced's tiny-skia software renderer wraps every window in a softbuffer::Surface to obtain a CPU-writable backbuffer. softbuffer 0.4 returns Err from Surface::new when it cannot turn the window's raw window handle into a platform surface: the backend matching the handle (X11, Wayland, Win32, AppKit) is unavailable, was compiled out, or the handle is not yet valid. iced treats this as unrecoverable and panics via .expect(\"Create softbuffer surface for window\").","triggerScenarios":"Running an iced application with the tiny-skia renderer when the window's platform handle does not match an available softbuffer backend: an X11 window under a Wayland session without XWayland, or a build of iced_tiny_skia/iced with default-features = false where the x11/wayland features (which forward to softbuffer/x11, softbuffer/wayland per tiny_skia/Cargo.toml:23-24) were dropped. Also triggered when create_surface is called before the window is fully realized on platforms where the raw handle is incomplete.","commonSituations":"Headless CI machines and Docker/SSH sessions with no display server; minimal feature-trimmed builds for embedded Linux boards (workspace pins softbuffer = { version = \"0.4\", default-features = false }); X11-vs-Wayland mismatches in Flatpak/sandboxed environments; softbuffer 0.3 to 0.4 upgrades where platform feature names changed.","solutions":["Run the application under a real display: set DISPLAY for X11/XWayland or WAYLAND_DISPLAY for Wayland","Re-enable the matching platform feature: iced = { features = [\"tiny-skia\", \"x11\"] } or \"wayland\" (they forward to softbuffer/x11 and softbuffer/wayland)","Verify the window handle type matches the active session (X11 window + Wayland session requires XWayland)","If no display server is available at all, switch to the wgpu renderer or use the offscreen screenshot() path instead of a window surface"],"exampleFix":"// before (Cargo.toml)\n[dependencies]\niced = { version = \"0.13\", default-features = false, features = [\"tiny-skia\"] }\n\n// after\n[dependencies]\niced = { version = \"0.13\", default-features = false, features = [\"tiny-skia\", \"x11\", \"wayland\"] }","handlingStrategy":"validation","validationCode":"// Before starting a tiny-skia (software) iced app on Linux:\nfn display_available() -> bool {\n    std::env::var(\"DISPLAY\").is_ok() || std::env::var(\"WAYLAND_DISPLAY\").is_ok()\n}\n\nif !display_available() {\n    eprintln!(\"no display server: enable iced x11/wayland features or run under XWayland\");\n    std::process::exit(1);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep the x11 and wayland features enabled on iced/iced_tiny_skia; they are what re-enable softbuffer backends (softbuffer is pinned with default-features = false)","Smoke-test window creation in CI with xvfb-run so a missing backend fails the build, not users","Confirm the window's platform matches the session (X11 window under Wayland needs XWayland)"],"tags":["softbuffer","tiny-skia","software-rendering","raw-window-handle","rust","gui"],"backgroundTag":"window-surface-creation-failed","analyzedSha":"3de451447bd28217bb535632867550908e29d5d0","analyzedAt":"2026-08-17T10:40:26.997Z","contentChangedAt":"2026-08-17T10:40:26.997Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}