{"record":{"id":"06a38c15c11d076b","repo":"tokio-rs/tokio","slug":"registering-signal-handler-failed","errorCode":null,"errorMessage":"registering signal handler failed","messagePattern":"registering signal handler failed","errorType":"exception","errorClass":"io::Error","httpStatus":null,"severity":"error","filePath":"tokio/src/signal/unix.rs","lineNumber":296,"sourceCode":"    // Check that we have a signal driver running\n    handle.check_inner()?;\n\n    let globals = globals();\n    let siginfo = match globals.storage().get(signal as EventId) {\n        Some(slot) => slot,\n        None => return Err(io::Error::new(io::ErrorKind::Other, \"signal too large\")),\n    };\n\n    siginfo\n        .init\n        .get_or_init(|| {\n            unsafe { signal_hook_registry::register(signal, move || action(globals, signal)) }\n                .map(|_| ())\n                .map_err(|e| e.raw_os_error())\n        })\n        .map_err(|e| {\n            e.map_or_else(\n                || Error::new(ErrorKind::Other, \"registering signal handler failed\"),\n                Error::from_raw_os_error,\n            )\n        })\n}\n\n/// An listener for receiving a particular type of OS signal.\n///\n/// The listener can be turned into a `Stream` using [`SignalStream`].\n///\n/// [`SignalStream`]: https://docs.rs/tokio-stream/latest/tokio_stream/wrappers/struct.SignalStream.html\n///\n/// In general signal handling on Unix is a pretty tricky topic, and this\n/// structure is no exception! There are some important limitations to keep in\n/// mind when using `Signal` streams:\n///\n/// * Signals handling in Unix already necessitates coalescing signals\n///   together sometimes. This `Signal` stream is also no exception here in\n///   that it will also coalesce signals. That is, even if the signal handler","sourceCodeStart":278,"sourceCodeEnd":314,"githubUrl":"https://github.com/tokio-rs/tokio/blob/625954f365727668cb02d04172b34f1149637728/tokio/src/signal/unix.rs#L278-L314","documentation":"signal_enable, in its init closure, calls signal_hook_registry::register and on failure maps the error to 'registering signal handler failed' (ErrorKind::Other) when raw_os_error is unavailable, or to the raw OS error otherwise. It means the OS-level sigaction registration failed.","triggerScenarios":"Registering a signal handler fails at the OS level: invalid signal, permission denied, or signal_hook_registry internals reject it; rare race during handler setup.","commonSituations":"Conflicting signal handlers set by a C library or another crate; calling signal() outside tokio that interferes; resource/threading limits during handler thread spawn; buggy platform ABI.","solutions":["Inspect the underlying raw_os_error if present (check e.raw_os_error()) for the OS errno.","Ensure only one framework (tokio) manages a given signal — remove manual libc::signal/libc::sigaction calls.","Register signals early at startup before any conflicting libraries do.","Update signal-hook / signal-hook-registry to a compatible version."],"exampleFix":"// before\nlet s = signal(kind)?; // 'registering signal handler failed'\n// after\nlet s = match signal(kind) {\n    Ok(s) => s,\n    Err(e) => {\n        eprintln!(\"errno={:?} kind={:?}\", e.raw_os_error(), e.kind());\n        return Err(e);\n    }\n};","handlingStrategy":"try-catch","validationCode":"// Register signals at startup before any other crate can claim them.\n// Ensure no other framework calls libc::signal/sigaction for the same signum.","typeGuard":null,"tryCatchPattern":"match signal(kind) {\n    Ok(s) => s,\n    Err(e) => {\n        eprintln!(\"signal register failed: errno={:?} kind={:?}\", e.raw_os_error(), e.kind());\n        return Err(e);\n    }\n}","preventionTips":["Register all signal handlers at process startup.","Avoid mixing tokio signal handling with manual libc sigaction for the same signal.","Keep signal-hook / signal-hook-registry versions consistent with tokio."],"tags":["signal","signal-handling","os-error","unix","io-error"],"backgroundTag":null,"analyzedSha":"625954f365727668cb02d04172b34f1149637728","analyzedAt":"2026-08-11T17:46:45.378Z","contentChangedAt":"2026-08-11T17:46:45.378Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}