iced-rs/iced · critical

Create event loop

Error message

Create event loop

What it means

The winit runtime panics when EventLoop::with_user_event().build() fails inside iced's run function. winit cannot create the platform event loop when the display server is unavailable or the platform is unsupported; iced treats a missing event loop as fatal because no GUI can run without it.

Solutions

1. Run in an environment with a display server; on Linux set DISPLAY or WAYLAND_DISPLAY correctly.
2. In CI/headless, use xvfb-run (Xvfb) or skip GUI startup in tests.
3. For WSL, ensure WSLg is enabled (Windows 11) or run an X server and export DISPLAY.
4. Verify winit's required platform features are enabled in your Cargo features/dependencies.
5. Check iced/winit versions for compatibility with your target platform.

Example fix

// before (CI)
cargo test
// after (CI)
xvfb-run -a cargo test

// shell preflight
[ -n "$DISPLAY" ] || [ -n "$WAYLAND_DISPLAY" ] || { echo "no display server"; exit 1; }

// probe display availability before starting the GUI loop
fn has_display() -> bool {
    std::env::var_os("WAYLAND_DISPLAY").is_some()
        || std::env::var_os("DISPLAY").is_some()
        || cfg!(target_os = "windows")
        || cfg!(target_os = "macos")
}
if !has_display() { eprintln!("No display available; running headless"); return; }

When it happens

Trigger: Calling iced run/application (winit backend) in an environment with no display: no DISPLAY/WAYLAND_DISPLAY on Linux, running in a headless CI container, SSH session without X forwarding, or a winit platform feature not compiled in.

Common situations: CI pipelines and Docker containers without X11/Wayland; WSL setups missing WSLg; tests invoking run() during cargo test; embedded/cross-compiled targets lacking winit support.

Understand the failure class

Background: "unsupported platform" / "not supported on this platform" errors: what they mean and how to fix them — this error's family across 47 libraries.

Related errors

• Append canvas to HTML body
• Create window
• Get window canvas
• Get window that was just inserted
• Send event

AI-assisted analysis of iced-rs/iced@fa3bae5287 (2026-09-11). Data as JSON: /api/errors/2d2f68efa10e297b. Report an issue: GitHub.

Appendix: source

Thrown at winit/src/lib.rs:83

use std::mem::ManuallyDrop;
use std::slice;
use std::sync::Arc;

/// Runs a [`Program`] with the provided settings.
pub fn run<P>(program: P) -> Result<(), Error>
where
    P: Program + 'static,
    P::Theme: theme::Base,
{
    use winit::event_loop::EventLoop;

    let boot_span = debug::boot();
    let settings = program.settings();
    let window_settings = program.window();

    let event_loop = EventLoop::with_user_event()
        .build()
        .expect("Create event loop");

    let backend_settings = backend::Settings::from(&settings);
    let renderer_settings = renderer::Settings::from(&settings);
    let display_handle = event_loop.owned_display_handle();

    let (proxy, worker) = Proxy::new(event_loop.create_proxy());

    #[cfg(feature = "debug")]
    {
        let proxy = proxy.clone();

        debug::on_hotpatch(move || {
            proxy.send_action(Action::Reload);
        });
    }

    let mut runtime = {
        let executor = P::Executor::new().map_err(Error::ExecutorCreationFailed)?;

View on GitHub (pinned to fa3bae5287)