ramensoftware/windhawk · critical

error while running the Windhawk UI

Error message

error while running the Windhawk UI

What it means

Rust Tauri application bootstrap in windhawk-core's ui::run. After building the Tauri app with the event system (broker state, splash readiness/presentation), .run(...) is unwrapped with .expect; if the Tauri runtime fails to start or the event loop errors, the process panics with 'error while running the Windhawk UI'.

Solutions

1. Check whether another Windhawk UI instance is already running (single-instance lock) and close it.
2. Verify tauri.conf.json is valid and that tauri::generate_context! matches the configured assets/icons.
3. Ensure the WebView2 runtime (or platform webview dependency) is installed and up to date, then relaunch.

// Before launching the UI process:
if (single_instance_lock_held()) {
    eprintln!("Windhawk UI already running");
    std::process::exit(0);
}
// And ensure webview runtime present before run().

if let Err(e) = tauri::Builder::default()
    .manage(/* ... */)
    .run(tauri::generate_context!())
{
    eprintln!("error while running the Windhawk UI: {e:#?}");
    std::process::exit(1);
}

When it happens

Trigger: tauri::Builder::run returns Err — typically a duplicate app instance / single-instance lock, invalid tauri.conf.json context, window creation failure, or plugin initialization error.

Common situations: Another Windhawk UI instance already holding the single-instance lock; corrupted or mismatched tauri.conf.json at build time; missing webview runtime (WebView2) on the machine.

Related errors

• spawn the event pump thread
• spawn the background startup thread
• Failed to load metadata for mod
• the mod cannot be stored in an archive, so it was not…
• the mod source could not be parsed, so its settings were…

AI-assisted analysis of ramensoftware/windhawk@61d99ed8e1 (2026-09-12). Data as JSON: /api/errors/74b56320b6d09906. Report an issue: GitHub.

Appendix: source

Thrown at src/windhawk-core/ui/src/lib.rs:775

                    // and the background catalog refresh.
                    pump::profile_watch::spawn(background_ctx.clone());
                    pump::startup::kick(&background_ctx);
                })
                .expect("spawn the background startup thread");

            Ok(())
        })
        .invoke_handler(tauri::generate_handler![
            wh_ipc,
            wh_log_backlog,
            wh_log_stop_capture,
            broker::wh_broker_state,
            broker::wh_broker_retry,
            splash::wh_splash_ready,
            splash::wh_splash_presented
        ])
        .run(tauri::generate_context!())
        .expect("error while running the Windhawk UI");
}

/// The stored UI theme setting, read from `getAppSettings` once at startup to seed the
/// native shell before the window opens. A read failure is the dark default (as is any
/// unrecognized value, per `ThemeSetting::parse`), matching the core's stored default and
/// the front-end.
fn startup_theme_setting(session: &dyn SessionApi) -> ThemeSetting {
    match session.invoke_as::<AppSettings, _>("getAppSettings", &json!({})) {
        Ok(settings) => ThemeSetting::parse(&settings.theme),
        Err(_) => ThemeSetting::Dark,
    }
}

/// Present a fatal failure as a native modal box, then terminate. Used where
/// there is no webview to render a reply into - which is every case here, since
/// what has failed is the window itself. `lead` is the sentence the box opens
/// with; `detail` is the explanation that follows it. Whatever the collectors
/// hold goes behind the box's expander, so the message stays a message and the

View on GitHub (pinned to 61d99ed8e1)