slint-ui/slint · critical

unable to show popup window

Error message

unable to show popup window

What it means

When a PopupWindow (ComboBox menu, context menu, tooltip) opens and the backend created a dedicated popup window adapter, Slint calls WindowAdapter::set_visible(true) on it; the .expect('unable to show popup window') turns any Err from the platform layer into a panic. The failure comes from the windowing system - mapping the real (top-level) popup window failed - not from application markup; the same popup usually works once the display/GPU environment is healthy.

Source

Thrown at internal/core/window.rs:2065

                    &clip_region,
                );
                self.window_adapter().request_redraw();
                (
                    PopupWindowLocation::ChildWindow(rect.origin),
                    Box::pin(PropertyTracker::new_with_dirty_handler(
                        PopupWindowPropertiesTracker {
                            parent_window_adapter_weak: parent_window_adapter_weak.clone(),
                            popup_id,
                        },
                    )),
                )
            } else {
                let popup_window = popup_window_adapter.window();
                WindowInner::from_pub(popup_window).set_component(popup_componentrc);
                popup_window.set_position(LogicalPosition::from_euclid(position));
                popup_window.set_size(WindowSize::Logical(LogicalSize::from_euclid(size)));

                popup_window_adapter.set_visible(true).expect("unable to show popup window");
                (
                    PopupWindowLocation::TopLevel(popup_window_adapter),
                    Box::pin(PropertyTracker::new_with_dirty_handler(
                        PopupWindowPropertiesTracker {
                            parent_window_adapter_weak: parent_window_adapter_weak.clone(),
                            popup_id,
                        },
                    )),
                )
            };

        let focus_item = if matches!(window_kind, WindowKind::ToolTip) {
            Default::default()
        } else {
            self.take_focus_item(&FocusEvent::FocusOut(FocusReason::PopupActivation))
                .map(|item| item.downgrade())
                .unwrap_or_default()
        };

View on GitHub (pinned to 3fd8f2ec03)

Solutions

  1. Provide a real display: run UI tests under xvfb-run (X11) or a headless weston compositor.
  2. If GPU-related, force the software renderer, e.g. SLINT_BACKEND=winit-software (or renderer-software feature), and update GPU drivers/mesa.
  3. Ensure the event loop and parent window exist on the same (main) thread before anything triggers popups.
  4. Reproduce with a minimal PopupWindow example and report it with backend/renderer and SLINT_DEBUG_LOG=1 output if the environment is healthy.

Example fix

# before: headless CI, opening a ComboBox menu panics 'unable to show popup window'
cargo test --test ui

# after: give the backend a display (or force software rendering)
xvfb-run -a cargo test --test ui
# alternatively: SLINT_BACKEND=winit-software cargo test --test ui
Defensive patterns

Strategy: try-catch

Validate before calling

// Cheap pre-flight before triggering popups: the parent window must
// still be shown on a live windowing connection.
if !window.is_visible() {
    // re-show or abort before opening the popup
}

Try / catch

// The panic fires inside popup show (e.g. ComboBox activation);
// isolate user-triggered popup entry points on flaky display setups:
let r = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
    ui.invoke("open-the-popup", &Default::default());
}));
if r.is_err() {
    log::error!("popup window could not be shown: display/GPU problem");
}

Prevention

When it happens

Trigger: Opening any PopupWindow when the winit backend tries to create a real OS popup window and the request fails: lost/broken X11 or Wayland connection, compositor rejecting the xdg_popup (invalid parent surface or position), GPU context/surface creation failure, or running headless with no display server at all.

Common situations: Headless CI running UI tests without Xvfb/weston; X-forwarding or remote desktop sessions with limited extensions; GPU driver reset while a menu was open; experimental backends with incomplete popup support; VMs without 3D acceleration.

Related errors

AI-assisted analysis of slint-ui/slint@3fd8f2ec03 (2026-08-19). Data as JSON: /api/errors/cae42effa3e768ca. Report an issue: GitHub.