tracel-ai/burn · error

failed to install Ctrl+C handler

Error message

failed to install Ctrl+C handler

What it means

os_shutdown_signal installs a tokio Ctrl+C handler; the expect panics if the handler cannot be installed. tokio::signal::ctrl_c() fails when the OS event registration errors (e.g. signal dispositions unavailable in the environment).

Source

Thrown at crates/burn-remote/src/server/spawn.rs:30

pub(crate) fn spawn_detached<F>(future: F)
where
    F: Future<Output = ()> + 'static,
{
    wasm_bindgen_futures::spawn_local(future);
}

/// Resolve when the process is asked to stop (Ctrl+C, or `SIGTERM` on Unix).
///
/// The single shutdown trigger shared by the turnkey WebSocket and Iroh server entry points.
#[cfg(all(
    not(target_family = "wasm"),
    any(feature = "websocket", feature = "iroh")
))]
pub(crate) async fn os_shutdown_signal() {
    let ctrl_c = async {
        tokio::signal::ctrl_c()
            .await
            .expect("failed to install Ctrl+C handler");
    };

    #[cfg(unix)]
    let terminate = async {
        tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate())
            .expect("failed to install signal handler")
            .recv()
            .await;
    };
    #[cfg(not(unix))]
    let terminate = std::future::pending::<()>();

    tokio::select! {
        _ = ctrl_c => {},
        _ = terminate => {},
    }
}

View on GitHub (pinned to d16f7ba2ed)

Solutions

1. Run the server in a normal OS process environment that supports SIGINT (not a restricted sandbox)
2. Provide a custom shutdown signal source instead of relying on ctrl_c
3. Check for code that previously set SIGINT to SIG_IGN or intercepted it incompatibly
4. Upgrade tokio if a signal-registration bug is suspected

Example fix

// before
server.start_async().await; // uses ctrl_c internally
// after
let shutdown = async { tokio::time::sleep(Duration::from_secs(3600)).await; }; // custom signal
server.start_async_with(shutdown).await; // if such an API exists, else run in supporting env

// Check the environment supports SIGINT before spawning the server
if !signal_supports_interrupt() { /* use custom shutdown future */ }

std::panic::catch_unwind(|| server_thread.join())
    .map_err(|_| anyhow!("server aborted: could not install Ctrl+C handler"))?;

When it happens

Trigger: Calling the server spawn path (websocket/iroh features) in an environment where SIGINT handling cannot be registered — embedded runtimes, containers without signal support, sandboxed environments.

Common situations: Running inside sandboxed CI or WASM-adjacent hosts lacking SIGINT; process already has conflicting signal handlers; resource exhaustion in the signal subsystem.

Related errors

• failed to install signal handler
• failed to install Ctrl+C handler
• failed to install signal handler
• Service call failed
• Service call failed

AI-assisted analysis of tracel-ai/burn@d16f7ba2ed (2026-09-05). Data as JSON: /api/errors/326906f7e372928d. Report an issue: GitHub.