{"record":{"id":"c41adba795153cc3","repo":"DioxusLabs/dioxus","slug":"tray-icon-builder-failed","errorCode":null,"errorMessage":"tray icon builder failed","messagePattern":"tray icon builder failed","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/desktop/src/trayicon.rs","lineNumber":45,"sourceCode":"#[allow(unused)]\npub fn init_tray_icon(menu: DioxusTrayMenu, icon: Option<DioxusTrayIcon>) -> DioxusTray {\n    #[cfg(any(target_os = \"windows\", target_os = \"linux\", target_os = \"macos\"))]\n    {\n        let icon = icon.map(Ok).unwrap_or_else(crate::default_icon);\n\n        let tray = tray_icon::TrayIconBuilder::new()\n            .with_menu(Box::new(menu))\n            .with_menu_on_left_click(false);\n\n        let tray = match icon {\n            Ok(icon) => tray.with_icon(icon),\n            Err(err) => {\n                tracing::trace!(\"No tray icon: {:?}\", err);\n                tray\n            }\n        };\n\n        provide_context(tray.build().expect(\"tray icon builder failed\"))\n    }\n}\n\n/// Returns a default tray icon menu\npub fn default_tray_icon() -> DioxusTrayMenu {\n    #[cfg(any(target_os = \"windows\", target_os = \"linux\", target_os = \"macos\"))]\n    {\n        use tray_icon::menu::{Menu, PredefinedMenuItem};\n        let tray_menu = Menu::new();\n        tray_menu\n            .append_items(&[&PredefinedMenuItem::quit(None)])\n            .unwrap();\n        tray_menu\n    }\n}\n\n/// Provides a hook to the tray icon\n#[cfg(any(target_os = \"windows\", target_os = \"linux\", target_os = \"macos\"))]","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/DioxusLabs/dioxus/blob/393d190a801ccb441d41923e232289b4f8a5c669/packages/desktop/src/trayicon.rs#L27-L63","documentation":"init_tray_icon builds the OS tray icon with tray-icon's TrayIconBuilder and unwraps the Result. On Linux the tray depends on the StatusNotifierItem protocol over dbus; on other desktops it depends on system APIs. When creation fails (no tray service reachable, wrong environment) the app panics at startup. Icon decoding errors are tolerated - only builder failure is fatal.","triggerScenarios":"Calling init_tray_icon on a Linux session without a system tray (bare window manager, GNOME without an AppIndicator extension, headless/WSL sessions) or in an environment where the tray backend cannot initialize.","commonSituations":"Developing or CI-running a tray-enabled desktop app headlessly; distros without an SNI provider installed; GNOME default session which ships no tray.","solutions":["Run the app inside a desktop session with a working tray (KDE, GNOME plus AppIndicator/Tray Icons extension, or a standalone tray)","Make the tray optional: only call init_tray_icon behind a CLI flag or runtime environment check","Elsewhere, use the safe hook use_tray_icon() -> Option<TrayIcon> so absence is handled gracefully","As a last resort wrap the init call in std::panic::catch_unwind so a tray-less environment does not kill the app"],"exampleFix":"// before\ninit_tray_icon(default_tray_icon(), None);\n\n// after\nuse dioxus_desktop::tao::platform::unix::...\nlet tray_ok = std::panic::catch_unwind(|| init_tray_icon(default_tray_icon(), None)).is_ok();\nif !tray_ok { tracing::warn!(\"system tray unavailable; continuing without it\"); }","handlingStrategy":"fallback","validationCode":"// Only create the tray when a desktop session plausibly has one\nfn tray_probably_available() -> bool {\n    #[cfg(target_os = \"linux\")]\n    {\n        std::env::var(\"XDG_CURRENT_DESKTOP\").is_ok() && std::env::var(\"DISPLAY\").is_ok()\n    }\n    #[cfg(not(target_os = \"linux\"))]\n    { true }\n}","typeGuard":null,"tryCatchPattern":"// Keep the app alive when the environment has no tray\nlet tray = std::panic::catch_unwind(|| {\n    init_tray_icon(default_tray_icon(), None)\n});\nif tray.is_err() { tracing::warn!(\"no system tray; running without tray icon\"); }","preventionTips":["Make the tray opt-in via a CLI flag or setting instead of unconditional at startup","Consume use_tray_icon() -> Option<TrayIcon> so UI degrades gracefully without a tray","On GNOME install an AppIndicator/Tray Icons extension; test on KDE or a standalone tray before shipping"],"tags":["desktop","tray-icon","linux","panic","runtime"],"backgroundTag":null,"analyzedSha":"393d190a801ccb441d41923e232289b4f8a5c669","analyzedAt":"2026-08-16T11:27:45.815Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}