{"record":{"id":"0b8bd135ea9e6eaf","repo":"GraphiteEditor/Graphite","slug":"failed-to-create-surface","errorCode":null,"errorMessage":"Failed to create surface","messagePattern":"Failed to create surface","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"desktop/src/window.rs","lineNumber":92,"sourceCode":"\t\tSelf {\n\t\t\twinit_window: winit_window.into(),\n\t\t\tnative_handle,\n\t\t\tcustom_cursors: HashMap::new(),\n\t\t\tclipboard,\n\t\t}\n\t}\n\n\tpub(crate) fn show(&self) {\n\t\tself.winit_window.set_visible(true);\n\t\tself.winit_window.focus_window();\n\t}\n\n\tpub(crate) fn request_redraw(&self) {\n\t\tself.winit_window.request_redraw();\n\t}\n\n\tpub(crate) fn create_surface(&self, instance: &WgpuInstance) -> WgpuSurface {\n\t\tinstance.create_surface(self.winit_window.clone()).expect(\"Failed to create surface\")\n\t}\n\n\tpub(crate) fn pre_present_notify(&self) {\n\t\tself.winit_window.pre_present_notify();\n\t}\n\n\tpub(crate) fn can_render(&self) -> bool {\n\t\tself.native_handle.can_render()\n\t}\n\n\tpub(crate) fn surface_size(&self) -> winit::dpi::PhysicalSize<u32> {\n\t\tself.winit_window.surface_size()\n\t}\n\n\tpub(crate) fn scale_factor(&self) -> f64 {\n\t\tself.winit_window.scale_factor()\n\t}\n","sourceCodeStart":74,"sourceCodeEnd":110,"githubUrl":"https://github.com/GraphiteEditor/Graphite/blob/c507b356453361e31638b8bff8f6d46b6da2961e/desktop/src/window.rs#L74-L110","documentation":"Panic when wgpu's instance.create_surface fails while creating the presentation surface from the winit window. create_surface returns a CreateSurfaceError when the platform cannot bind the window's raw handle to a GPU surface: missing/unsupported windowing backend (Wayland vs X11 mismatches), missing EGL/Vulkan client libraries, unsupported window types, or a stale/invalid window handle.","triggerScenarios":"Running on Linux without the required EGL/Vulkan libraries (libEGL, libvulkan loader, X11 GLX libs) present; running under Xvfb or a VNC session with no accelerated visuals; a Wayland/X11 mismatch between winit and the installed graphics stack; creating the surface after the window handle has become invalid.","commonSituations":"Minimal Linux/container environments lacking the client GL libraries; remote desktop sessions without GPU support; systems where only software rendering is available but the surface backend can't attach to it; version mismatches between wgpu and winit raw-window-handle versions.","solutions":["Install the platform GL client libraries (libegl1, libgl1, libvulkan1, and X11/Wayland variants) and retry","Force the other windowing backend (run under XWayland or a native Wayland session) to rule out backend mismatch","Print/inspect the CreateSurfaceError variant to identify which backend is failing","In headless environments, run the editor with a virtual display that exposes at least software GL (e.g., Xvfb + swrast) or use the web build"],"exampleFix":"// before\ninstance.create_surface(self.winit_window.clone()).expect(\"Failed to create surface\")\n\n// after\ninstance.create_surface(self.winit_window.clone()).unwrap_or_else(|e| panic!(\"Failed to create surface: {e}\"))","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"match instance.create_surface(self.winit_window.clone()) {\n\tOk(surface) => surface,\n\tErr(e) => {\n\t\teprintln!(\"Failed to create surface: {e}\");\n\t\teprintln!(\"Install EGL/Vulkan client libraries or try the other windowing backend (Wayland vs X11).\");\n\t\tstd::process::exit(1);\n\t}\n}","preventionTips":["Install the platform GL client libraries (libEGL, libvulkan, X11/Wayland GL packages) on minimal systems","Test both Wayland and X11 sessions when surface creation fails on Linux","Log the CreateSurfaceError variant; it names the failing backend and reason"],"tags":["rust","wgpu","winit","surface","graphics-platform"],"backgroundTag":"egl-surface-creation-failed","analyzedSha":"c507b356453361e31638b8bff8f6d46b6da2961e","analyzedAt":"2026-08-16T21:57:18.596Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}