{"record":{"id":"0b98487fb7a7d7c8","repo":"zed-industries/zed","slug":"idle-sleep-prevention-for-reason-requires-a-linux-windowing","errorCode":null,"errorMessage":"Idle sleep prevention for {reason:?} requires a Linux windowing backend","messagePattern":"Idle sleep prevention for (.+?) requires a Linux windowing backend","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/gpui_linux/src/linux/platform.rs","lineNumber":297,"sourceCode":"\n    fn keyboard_mapper(&self) -> Rc<dyn PlatformKeyboardMapper> {\n        Rc::new(gpui::DummyKeyboardMapper)\n    }\n\n    fn on_keyboard_layout_change(&self, callback: Box<dyn FnMut()>) {\n        self.inner\n            .with_common(|common| common.callbacks.keyboard_layout_change = Some(callback));\n    }\n\n    fn on_thermal_state_change(&self, _callback: Box<dyn FnMut()>) {}\n\n    fn thermal_state(&self) -> ThermalState {\n        ThermalState::Nominal\n    }\n\n    #[cfg(not(any(feature = \"wayland\", feature = \"x11\")))]\n    fn prevent_idle_sleep(&self, reason: &str) -> Task<Result<ActivityGuard>> {\n        Task::ready(Err(anyhow!(\n            \"Idle sleep prevention for {reason:?} requires a Linux windowing backend\"\n        )))\n    }\n\n    #[cfg(any(feature = \"wayland\", feature = \"x11\"))]\n    fn prevent_idle_sleep(&self, reason: &str) -> Task<Result<ActivityGuard>> {\n        let executor = self.background_executor();\n        let (guard_tx, guard_rx) = oneshot::channel();\n        executor\n            .spawn({\n                let executor = executor.clone();\n                let reason = reason.to_owned();\n                async move {\n                    guard_tx\n                        .send(inhibit_idle_sleep(reason, executor).await)\n                        .ok();\n                }\n            })","sourceCodeStart":279,"sourceCodeEnd":315,"githubUrl":"https://github.com/zed-industries/zed/blob/9d272b036335401f339d024ea94968fd51016c40/crates/gpui_linux/src/linux/platform.rs#L279-L315","documentation":"On Linux, gpui's Platform::prevent_idle_sleep is only implemented when the wayland or x11 Cargo feature is enabled. When neither backend is compiled in, the stub implementation returns this error immediately instead of returning an ActivityGuard. It signals that the library build itself lacks any mechanism to inhibit idle sleep.","triggerScenarios":"Calling prevent_idle_sleep (e.g. to keep the screen awake during a call or long operation) on a Linux platform instance built without the `wayland` or `x11` features, i.e. a headless/backend-less gpui build.","commonSituations":"See trigger scenarios.","solutions":["Build gpui with a windowing backend: enable the `wayland` or `x11` feature (Zed does this by default on Linux).","Use a build of Zed compiled with display backend support rather than a headless/custom build.","If running headless is intentional, treat this error as expected and skip idle-sleep prevention calls in that environment.","Check the build configuration if you built from source with `--no-default-features` and re-enable the backend feature."],"exampleFix":"// before: building without a backend\ncargo build --no-default-features\n\n// after: enable a Linux windowing backend\ncargo build --features x11","handlingStrategy":"fallback","validationCode":"// At runtime, detect headless Linux before requesting idle inhibition\nlet headless = std::env::var_os(\"WAYLAND_DISPLAY\").is_none()\n    && std::env::var_os(\"DISPLAY\").is_none();","typeGuard":null,"tryCatchPattern":"match platform.prevent_idle_sleep(\"call\") {\n    Task::Ready(fut) => match fut.await {\n        Err(e) if e.to_string().contains(\"requires a Linux windowing backend\") => {\n            log::warn!(\"headless build: continuing without idle-sleep prevention\");\n        }\n        other => other?,\n    },\n    task => task.await?,\n}","preventionTips":["Build gpui/Zed on Linux with the wayland or x11 feature enabled (default Zed builds do).","Avoid --no-default-features builds for GUI deployments.","Detect headless environments early and skip idle-sleep features there.","Document that idle-sleep prevention requires a display backend in embedded uses of gpui."],"tags":["linux","gpui","idle-sleep","feature-flags","headless"],"backgroundTag":"feature-not-enabled","analyzedSha":"9d272b036335401f339d024ea94968fd51016c40","analyzedAt":"2026-09-12T19:35:53.743Z","contentChangedAt":"2026-09-12T19:35:53.743Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}