tinyhumansai/openhuman · error

failed to install SIGTERM handler

Error message

failed to install SIGTERM handler

What it means

Panic payload when tokio::signal::unix::signal(SignalKind::terminate()) fails during wait_for_signal(): installing the SIGTERM handler can fail if the runtime lacks signal-driver support or the process environment forbids it. The expect aborts the shutdown waiter, so the process loses graceful SIGTERM handling.

Source

Thrown at src/core/shutdown.rs:82

/// fail rustdoc.)
pub async fn signal() {
    // Wait for the OS to send a termination signal.
    wait_for_signal().await;
    log::info!("[core] shutdown signal received, cleaning up background services");
    // Once received, run all registered cleanup tasks.
    run_hooks().await;
    log::info!("[core] all shutdown hooks completed");
}

/// Wait for either SIGINT (Ctrl-C) or SIGTERM (Unix termination signal).
///
/// This uses `tokio::signal` to asynchronously wait for these events.
async fn wait_for_signal() {
    #[cfg(unix)]
    {
        use tokio::signal::unix::{signal, SignalKind};
        let mut sigterm =
            signal(SignalKind::terminate()).expect("failed to install SIGTERM handler");
        tokio::select! {
            _ = tokio::signal::ctrl_c() => {
                log::info!("[core] received SIGINT (Ctrl-C)");
            }
            _ = sigterm.recv() => {
                log::info!("[core] received SIGTERM");
            }
        }
    }

    #[cfg(not(unix))]
    {
        // On non-Unix platforms (like Windows), we only listen for Ctrl-C.
        let _ = tokio::signal::ctrl_c().await;
        log::info!("[core] received SIGINT (Ctrl-C)");
    }
}

View on GitHub (pinned to 7491200858)

Solutions

1. Ensure shutdown::signal() runs on a tokio runtime with signal support enabled (not a current-thread runtime without the IO driver)
2. Register the handler before entering any code that masks SIGTERM
3. Fall back to catching SIGINT only or a plain ctrl_c() stream when SIGTERM registration fails

When it happens

Trigger: Thrown at src/core/shutdown.rs:82 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of tinyhumansai/openhuman@7491200858 (2026-08-17). Data as JSON: /api/errors/f16eeacb411249df. Report an issue: GitHub.