{"record":{"id":"a4779accc9d66f3f","repo":"tracel-ai/burn","slug":"failed-to-install-signal-handler-a4779a","errorCode":null,"errorMessage":"failed to install signal handler","messagePattern":"failed to install signal handler","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/burn-remote/src/server/spawn.rs","lineNumber":36,"sourceCode":"\n/// Resolve when the process is asked to stop (Ctrl+C, or `SIGTERM` on Unix).\n///\n/// The single shutdown trigger shared by the turnkey WebSocket and Iroh server entry points.\n#[cfg(all(\n    not(target_family = \"wasm\"),\n    any(feature = \"websocket\", feature = \"iroh\")\n))]\npub(crate) async fn os_shutdown_signal() {\n    let ctrl_c = async {\n        tokio::signal::ctrl_c()\n            .await\n            .expect(\"failed to install Ctrl+C handler\");\n    };\n\n    #[cfg(unix)]\n    let terminate = async {\n        tokio::signal::unix::signal(tokio::signal::unix::SignalKind::terminate())\n            .expect(\"failed to install signal handler\")\n            .recv()\n            .await;\n    };\n    #[cfg(not(unix))]\n    let terminate = std::future::pending::<()>();\n\n    tokio::select! {\n        _ = ctrl_c => {},\n        _ = terminate => {},\n    }\n}\n","sourceCodeStart":18,"sourceCodeEnd":48,"githubUrl":"https://github.com/tracel-ai/burn/blob/d16f7ba2ed0d41408189384044cc886fb4c8f957/crates/burn-remote/src/server/spawn.rs#L18-L48","documentation":"On Unix targets, os_shutdown_signal registers a SIGTERM listener via tokio::signal::unix::signal and expects installation to succeed. Failure means the OS/registry rejected creating the signal stream.","triggerScenarios":"Server startup with websocket/iroh features on Unix where SignalKind::terminate registration fails — signal mask manipulated by parent process, fd/resource exhaustion, or unsupported platform quirks.","commonSituations":"Containers/init systems that block or mask SIGTERM; exceeding per-process signal-stream limits; running under sandboxes that forbid signal registration.","solutions":["Ensure the parent process doesn't block SIGTERM before spawning the server","Verify the runtime environment allows unix signal registration (no restrictive seccomp/sandbox rule)","Replace the default shutdown signal with a custom future if SIGTERM handling is unavailable","Check available file descriptors / raise ulimit -n, since signal streams consume fds"],"exampleFix":"// before\ntokio::signal::unix::signal(SignalKind::terminate()).expect(\"failed to install signal handler\");\n// after\nmatch tokio::signal::unix::signal(SignalKind::terminate()) {\n    Ok(mut sig) => sig.recv().await,\n    Err(e) => { log::warn!(\"SIGTERM handler unavailable: {e}; falling back\"); std::future::pending::<()>().await }\n}","handlingStrategy":"fallback","validationCode":"// Ensure SIGTERM is not blocked by this process before starting the server\nunsafe { assert!(!signal_blocked(libc::SIGTERM)); }","typeGuard":null,"tryCatchPattern":"std::panic::catch_unwind(|| server_thread.join())\n    .map_err(|_| anyhow!(\"server aborted: could not install SIGTERM handler\"))?;","preventionTips":["Don't block SIGTERM in the parent process before spawning the server","Raise fd limits (ulimit -n) since signal streams consume descriptors","Provide a custom shutdown mechanism in sandboxes that forbid signal registration"],"tags":["rust","tokio","unix","signals"],"backgroundTag":"signal-handler-install-failed","analyzedSha":"d16f7ba2ed0d41408189384044cc886fb4c8f957","analyzedAt":"2026-09-05T13:19:14.260Z","contentChangedAt":"2026-09-05T13:19:14.260Z","schemaVersion":2},"datasetVersion":"2026-09-12T17:17:11.597Z"}