zed-industries/zed · error

Idle sleep prevention for {reason:?} requires a Linux window

Error message

Idle sleep prevention for {reason:?} requires a Linux windowing backend

What it means

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.

Source

Thrown at crates/gpui_linux/src/linux/platform.rs:297

    fn keyboard_mapper(&self) -> Rc<dyn PlatformKeyboardMapper> {
        Rc::new(gpui::DummyKeyboardMapper)
    }

    fn on_keyboard_layout_change(&self, callback: Box<dyn FnMut()>) {
        self.inner
            .with_common(|common| common.callbacks.keyboard_layout_change = Some(callback));
    }

    fn on_thermal_state_change(&self, _callback: Box<dyn FnMut()>) {}

    fn thermal_state(&self) -> ThermalState {
        ThermalState::Nominal
    }

    #[cfg(not(any(feature = "wayland", feature = "x11")))]
    fn prevent_idle_sleep(&self, reason: &str) -> Task<Result<ActivityGuard>> {
        Task::ready(Err(anyhow!(
            "Idle sleep prevention for {reason:?} requires a Linux windowing backend"
        )))
    }

    #[cfg(any(feature = "wayland", feature = "x11"))]
    fn prevent_idle_sleep(&self, reason: &str) -> Task<Result<ActivityGuard>> {
        let executor = self.background_executor();
        let (guard_tx, guard_rx) = oneshot::channel();
        executor
            .spawn({
                let executor = executor.clone();
                let reason = reason.to_owned();
                async move {
                    guard_tx
                        .send(inhibit_idle_sleep(reason, executor).await)
                        .ok();
                }
            })

View on GitHub (pinned to 9d272b0363)

Solutions

1. Build gpui with a windowing backend: enable the `wayland` or `x11` feature (Zed does this by default on Linux).
2. Use a build of Zed compiled with display backend support rather than a headless/custom build.
3. If running headless is intentional, treat this error as expected and skip idle-sleep prevention calls in that environment.
4. Check the build configuration if you built from source with `--no-default-features` and re-enable the backend feature.

Example fix

// before: building without a backend
cargo build --no-default-features

// after: enable a Linux windowing backend
cargo build --features x11

// At runtime, detect headless Linux before requesting idle inhibition
let headless = std::env::var_os("WAYLAND_DISPLAY").is_none()
    && std::env::var_os("DISPLAY").is_none();

match platform.prevent_idle_sleep("call") {
    Task::Ready(fut) => match fut.await {
        Err(e) if e.to_string().contains("requires a Linux windowing backend") => {
            log::warn!("headless build: continuing without idle-sleep prevention");
        }
        other => other?,
    },
    task => task.await?,
}

When it happens

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

Common situations: See trigger scenarios.

Related errors

• Idle sleep prevention request was abandoned
• Idle sleep prevention acquisition timed out after 10 seconds
• blocking sender returned without value
• No GPU adapters found
• wl_seat below required version: {} < {}

AI-assisted analysis of zed-industries/zed@9d272b0363 (2026-09-12). Data as JSON: /api/errors/0b98487fb7a7d7c8. Report an issue: GitHub.