{"record":{"id":"cee54d20418376d4","repo":"wezterm/wezterm","slug":"failed-to-create-csd-frame","errorCode":null,"errorMessage":"failed to create csd frame","messagePattern":"failed to create csd frame","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"window/src/os/wayland/window.rs","lineNumber":270,"sourceCode":"\n        window.set_app_id(class_name.to_string());\n        window.set_title(name.to_string());\n\n        let decor_mode = if !config.window_decorations.contains(WindowDecorations::TITLE) {\n            None\n        } else if config.window_decorations == WindowDecorations::default() {\n            Some(DecorationMode::Server)\n        } else {\n            Some(DecorationMode::Client)\n        };\n        window.request_decoration_mode(decor_mode);\n\n        let mut window_frame = {\n            let wayland_state = &conn.wayland_state.borrow();\n            let shm = &wayland_state.shm;\n            let subcompositor = wayland_state.subcompositor.clone();\n            FallbackFrame::new(&window, shm, subcompositor, qh.clone())\n                .expect(\"failed to create csd frame\")\n        };\n        let hidden = match decor_mode {\n            Some(DecorationMode::Client) => false,\n            _ => true,\n        };\n        window_frame.set_hidden(hidden);\n        if !hidden {\n            window_frame.resize(\n                NonZeroU32::new(dimensions.pixel_width as u32)\n                    .ok_or_else(|| anyhow!(\"dimensions {dimensions:?} are invalid\"))?,\n                NonZeroU32::new(dimensions.pixel_height as u32)\n                    .ok_or_else(|| anyhow!(\"dimensions {dimensions:?} are invalid\"))?,\n            );\n        }\n\n        window.set_min_size(Some((32, 32)));\n        let (x, y) = window_frame.location();\n        let surface_width = dimensions.pixels_to_surface(dimensions.pixel_width as i32);","sourceCodeStart":252,"sourceCodeEnd":288,"githubUrl":"https://github.com/wezterm/wezterm/blob/08e5e0afc6007567d3d131bc2ec1382423c0d2da/window/src/os/wayland/window.rs#L252-L288","documentation":"Every Wayland window wezterm creates instantiates a FallbackFrame (client-side decoration frame) regardless of the negotiated decoration mode; it is only hidden when server-side decorations are active. FallbackFrame::new binds subcompositor surfaces for the borders/title bar, and any failure (missing wl_subcompositor global, shm failure, surface creation error) panics here.","triggerScenarios":"Fires at window creation (Window::new) on Wayland. Typical causes: the compositor does not expose the wl_subcompositor global needed to place border surfaces, or the shm/subsurface pool setup fails right after — often the same resource pressure that breaks the pointer/frame pools.","commonSituations":"Running against minimal or embedded compositors (kiosk Wayland servers, cage, some nested compositors) that omit wl_subcompositor; fd/memory exhaustion at startup; protocol version mismatches in older wezterm builds.","solutions":["Check that the compositor provides wl_subcompositor: `wayland-info` (weston-info) must list it alongside wl_compositor and wl_shm","Rule out resource exhaustion: raise `ulimit -n` and confirm memory is available, since subcompositor surface/pool creation can fail like any shm allocation","Update wezterm — FallbackFrame construction and decoration negotiation have seen multiple fixes","As a last resort on a limited compositor, force the X11 path with WEZTERM_ENABLE_WAYLAND=0 (requires XWayland)"],"exampleFix":"# before: panic 'failed to create csd frame' on a compositor without wl_subcompositor\nwayland-info | grep -i subcompositor   # no output = missing global\nWEZTERM_ENABLE_WAYLAND=0 wezterm       # after: runs via XWayland","handlingStrategy":"fallback","validationCode":"# check that the compositor provides the subcompositor global\nwayland-info | grep -i subcompositor","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Prefer compositors that expose wl_subcompositor for full CSD support","Keep WEZTERM_ENABLE_WAYLAND=0 as a documented escape hatch on limited compositors (needs XWayland)","Validate compositor globals (wayland-info) when certifying kiosk/embedded images"],"tags":["wayland","client-side-decorations","subcompositor","window-creation","panic"],"backgroundTag":"missing-wayland-protocol-global","analyzedSha":"08e5e0afc6007567d3d131bc2ec1382423c0d2da","analyzedAt":"2026-08-20T04:47:31.434Z","contentChangedAt":"2026-08-20T04:47:31.434Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}