{"record":{"id":"116a1333087d70df","repo":"atuinsh/atuin","slug":"failed-to-register-signal-handler","errorCode":null,"errorMessage":"failed to register signal handler","messagePattern":"failed to register signal handler","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/atuin-server/src/lib.rs","lineNumber":30,"sourceCode":"\nmod handlers;\nmod metrics;\nmod router;\nmod trace;\n\npub mod db;\n\npub use settings::{Settings, example_config};\n\npub mod settings;\n\nuse tokio::net::TcpListener;\nuse tokio::signal;\n\n#[cfg(target_family = \"unix\")]\nasync fn shutdown_signal() {\n    let mut term = signal::unix::signal(signal::unix::SignalKind::terminate())\n        .expect(\"failed to register signal handler\");\n    let mut interrupt = signal::unix::signal(signal::unix::SignalKind::interrupt())\n        .expect(\"failed to register signal handler\");\n\n    tokio::select! {\n        _ = term.recv() => {},\n        _ = interrupt.recv() => {},\n    };\n    eprintln!(\"Shutting down gracefully...\");\n}\n\n#[cfg(target_family = \"windows\")]\nasync fn shutdown_signal() {\n    signal::windows::ctrl_c().expect(\"failed to register signal handler\").recv().await;\n    eprintln!(\"Shutting down gracefully...\");\n}\n\npub async fn launch(settings: Settings, addr: SocketAddr) -> Result<()> {\n    launch_with_tcp_listener(","sourceCodeStart":12,"sourceCodeEnd":48,"githubUrl":"https://github.com/atuinsh/atuin/blob/900007c48045867e7f44b0f9bc55ad9dbe99ee0d/crates/atuin-server/src/lib.rs#L12-L48","documentation":"`shutdown_signal` on Unix registers a SIGTERM handler with tokio and panics via `.expect(\"failed to register signal handler\")` if registration fails. tokio's signal registration fails when the OS refuses the handler installation — typically when not running on a real OS thread setup that supports signals, when the process has no permission for the signal, or when signal dispositions are externally controlled.","triggerScenarios":"Calling `launch` or `launch_metrics_server` in an environment where `signal::unix::signal(SignalKind::terminate())` returns Err — e.g. running inside restricted containers/seccomp sandboxes that block sigaction, or after tokio runtime misuse.","commonSituations":"Docker containers with hardened seccomp profiles, restricted CI runners, unusual sandboxing (gVisor), or embedding the server in a non-tokio runtime context.","solutions":["Check the container/sandbox security profile allows sigaction for SIGTERM/SIGINT","Ensure the server runs on a proper multi-thread tokio runtime","Replace expect with graceful degradation: log a warning and fall back to waiting on ctrl_c or indefinitely"],"exampleFix":"// before\nlet mut term = signal::unix::signal(signal::unix::SignalKind::terminate())\n    .expect(\"failed to register signal handler\");\n// after\nlet mut term = signal::unix::signal(signal::unix::SignalKind::terminate())\n    .unwrap_or_else(|e| {\n        eprintln!(\"failed to register SIGTERM handler: {e}; skipping graceful shutdown on SIGTERM\");\n        signal::unix::signal(signal::unix::SignalKind::hangup()).expect(\"failed to register signal handler\")\n    });","handlingStrategy":"try-catch","validationCode":"// check before serving (unix)\nlet term_ok = signal::unix::signal(signal::unix::SignalKind::terminate()).is_ok();","typeGuard":null,"tryCatchPattern":"match signal::unix::signal(signal::unix::SignalKind::terminate()) {\n    Ok(mut s) => { /* proceed with shutdown select */ }\n    Err(e) => eprintln!(\"SIGTERM handler unavailable: {e}\"),\n}","preventionTips":["Run the server with a standard tokio multi_thread runtime","Relax seccomp/sandbox profiles to allow sigaction for SIGTERM/SIGINT","Test server startup inside your actual container/sandbox image"],"tags":["panic","signals","unix","server","shutdown"],"backgroundTag":"module-init-failed","analyzedSha":"900007c48045867e7f44b0f9bc55ad9dbe99ee0d","analyzedAt":"2026-09-19T12:52:51.491Z","contentChangedAt":"2026-09-19T12:52:51.491Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}