atuinsh/atuin · error

failed to register signal handler

Error message

failed to register signal handler

What it means

When the sync server boots, atuin_server::launch() spawns shutdown_signal(), which registers a SIGTERM listener via tokio::signal::unix::signal. Registration fails if the current runtime has no IO/signal driver or the OS denies the operation, and the expect panics with 'failed to register signal handler', aborting server startup.

Source

Thrown at crates/atuin-server/src/lib.rs:26

use eyre::{Context, Result};

mod handlers;
mod metrics;
mod router;
mod trace;

pub use settings::Settings;
pub use settings::example_config;

pub mod settings;

use tokio::net::TcpListener;
use tokio::signal;

#[cfg(target_family = "unix")]
async fn shutdown_signal() {
    let mut term = signal::unix::signal(signal::unix::SignalKind::terminate())
        .expect("failed to register signal handler");
    let mut interrupt = signal::unix::signal(signal::unix::SignalKind::interrupt())
        .expect("failed to register signal handler");

    tokio::select! {
        _ = term.recv() => {},
        _ = interrupt.recv() => {},
    };
    eprintln!("Shutting down gracefully...");
}

#[cfg(target_family = "windows")]
async fn shutdown_signal() {
    signal::windows::ctrl_c()
        .expect("failed to register signal handler")
        .recv()
        .await;
    eprintln!("Shutting down gracefully...");
}

View on GitHub (pinned to 202f6ad98e)

Solutions

1. Run the server through atuin_server::launch as the shipped binary does, inside a fully enabled runtime
2. Build any hosting runtime with .enable_all() before awaiting launch
3. Raise LimitNOFILE / memory if boot-time registration fails

Example fix

// before
let rt = tokio::runtime::Builder::new_multi_thread().build()?;

// after — signal registration needs the IO driver
let rt = tokio::runtime::Builder::new_multi_thread()
    .enable_all()
    .build()?;

let rt = tokio::runtime::Builder::new_multi_thread()
    .enable_all() // signal registration requires the IO driver
    .build()?;
rt.block_on(async { atuin_server::launch::<Db>(settings, addr).await })?;

match tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate()) {
    Ok(term) => tokio::select! { _ = term.recv() => {} },
    Err(e) => {
        eprintln!("sigterm handler unavailable: {e}; relying on SIGINT");
        tokio::signal::unix::signal(tokio::signal::unix::SignalKind::interrupt())
            .expect("sigint")
            .recv()
            .await;
    }
}

When it happens

Trigger: Calling atuin_server::launch/launch_with_tcp_listener from a tokio runtime built without enable_all()/enable_io(); fd or memory exhaustion (EMFILE) while installing the signal machinery; sandboxes blocking sigaction.

Common situations: Embedding the sync server (axum host apps, custom binaries) in a runtime lacking the IO driver; resource-starved containers at boot.

Related errors

• failed to register sigterm handler
• failed to register sigint handler
• failed to listen for ctrl+c
• bug in list query. please report
• bug in search query. please report

AI-assisted analysis of atuinsh/atuin@202f6ad98e (2026-08-16). Data as JSON: /api/errors/116a1333087d70df. Report an issue: GitHub.