tracel-ai/burn · error

failed to install signal handler

Error message

failed to install signal handler

What it means

This panic fires when tokio's unix::signal(SignalKind::terminate()) fails to register a SIGTERM handler in os_shutdown_signal(). Failure means the tokio signal driver is unavailable in the current runtime. The library treats inability to observe termination signals as fatal since graceful shutdown could never complete.

Source

Thrown at crates/burn-communication/src/util.rs:12

/// Utilities to help handle communication termination.
pub 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. Build the tokio runtime with .enable_all() (or at minimum the signal driver) so SignalKind::terminate() registration succeeds.
2. Verify the tokio crate dependency includes the 'signal' feature.
3. Run the async start functions within a proper tokio::main / tokio::run context rather than a hand-rolled executor.

Example fix

// before
tokio::runtime::Builder::new_multi_thread().enable_io().build()?;
// after
tokio::runtime::Builder::new_multi_thread().enable_all().build()?;

#[cfg(unix)]
assert!(tokio::runtime::Handle::try_current().is_ok(), "SIGTERM handler needs a tokio runtime with the signal driver");

When it happens

Trigger: Calling start_iroh_async or start_websocket_async on Unix inside a runtime without the signal driver enabled; tokio::signal::unix::signal returns Err during os_shutdown_signal startup.

Common situations: Minimal tokio feature sets in embedded applications (e.g. no 'signal' feature), custom runtimes that skipped enable_all(), or platforms/configs where registering SIGTERM is disallowed.

Related errors

• failed to install Ctrl+C handler
• failed to install signal handler
• capture tensor operations must run inside CaptureDevice::cap
• Capture tensors do not support autodiff
• Autodiff should not wrap an autodiff tensor.

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