VALKEY-SIGNALS(7)

💖 VALKEY-SIGNALS 💖

okay bestie, welcome to the valkey-signals page — this is the one about signal handling, aka how Valkey reacts when the operating system comes knocking with a POSIX signal. think SIGTERM, think SIGSEGV, think ✨vibes✨. it's a manual page (section 7, if you're keeping score), so let's get into it 🫶

---

🌸 DESCRIPTION 🌸

this whole doc is basically the tea on how Valkey behaves when it catches different POSIX signals — you know, the big ones like SIGTERM and SIGSEGV. no cap, this is important stuff.

😌 SIGTERM and SIGINT — the gentle "please wrap it up" signals

so SIGTERM and SIGINT are the polite ones. they tell Valkey to shut down gracefully. and the key word there is gracefully, because Valkey does not just immediately exit when it gets one of these. nope. instead it schedules a shutdown — basically the same kind of shutdown you'd get from the SHUTDOWN command.

when does the scheduled shutdown actually kick in? as soon as possible, fr fr — specifically, as long as the current command in execution terminates (if there's one running), plus maybe a lil extra delay of 0.1 seconds or less. so, quick.

💀 little snag: if the server is blocked by a long-running Lua script, you're gonna need to kill that script with SCRIPT KILL if you can. the scheduled shutdown will run just after the script gets killed or terminates spontaneously. so handle that first, bestie.

this shutdown process includes the following actions:

• if there are any replicas lagging behind in replication:
  • pause clients attempting to write with CLIENT PAUSE and the WRITE option.
  • wait up to the configured shutdown-timeout (default 10 seconds) for replicas to catch up with the primary's replication offset.
• if a background child is saving the RDB file or performing an AOF rewrite, the child process is killed.
• if the AOF is active, Valkey calls the fsync system call on the AOF file descriptor to flush the buffers on disk.
• if Valkey is configured to persist on disk using RDB files, a synchronous (blocking) save is performed. since the save is synchronous, it doesn't use any additional memory. slay.
• if the server is daemonized, the PID file is removed.
• if the Unix domain socket is enabled, it gets removed.
• the server exits with an exit code of zero. periodt.

BUT — and this is a big but — IF the RDB file can't be saved, the shutdown fails, and the server just keeps running, because the whole point is making sure there's no data loss. same energy if the user just turned on AOF and the server triggered the first AOF rewrite to create the initial AOF file, but that file can't be saved: shutdown fails, server keeps running. and no further attempt to shut down will be made unless a new SIGTERM is received or the SHUTDOWN command is issued. noted 📝

here's the history lesson part, iykyk: since Redis OSS 7.0, the server waits for lagging replicas up to a configurable shutdown-timeout, 10 seconds by default, before shutting down. this is a best effort to minimize the risk of data loss in a situation where no save points are configured and AOF is deactivated. before version 7.0, shutting down a heavily loaded primary node in a diskless setup was more likely to result in data loss. 😭

to minimize the risk of data loss in such setups, trigger a manual FAILOVER (or CLUSTER FAILOVER) to demote the primary to a replica and promote one of the replicas to a new primary before shutting down a primary node. do it in that order. trust. 🙏

---

💥 SIGSEGV, SIGBUS, SIGFPE and SIGILL — the "we're crashing" signals

these following signals are handled as a Valkey crash:

• SIGSEGV
• SIGBUS
• SIGFPE
• SIGILL

once one of these signals is trapped, Valkey stops any current operation and performs the following actions:

• adds a bug report to the log file. this includes a stack trace, dump of registers, and information about the state of clients. receipts, basically.
• a fast memory test is performed as a first check of the reliability of the crashing system.
• if the server was daemonized, the PID file is removed.
• finally, the server unregisters its own signal handler for the received signal and resends the same signal to itself, to make sure that the default action is performed — such as dumping the core on the file system.

---

👻 What happens when a child process gets killed

so when the child performing the Append Only File rewrite gets killed by a signal, Valkey handles this as an error and discards the (probably partial or corrupted) AOF file. it will attempt the rewrite again later. no biggie, it recovers.

when the child performing an RDB save is killed, that's a more severe error. and here's why the distinction matters: while the failure of an AOF file rewrite can cause AOF file enlargement, failed RDB file creation reduces durability. 😬

as a result of the child producing the RDB file being killed by a signal, or when the child exits with an error (non zero exit code), Valkey enters a special error condition where no further write command is accepted.

• Valkey will continue to reply to read commands.
• Valkey will reply to all write commands with a MISCONFIG error.

this error condition will persist until it becomes possible to create an RDB file successfully. so like, it's stuck in its feels until it can save again 💅

---

🎀 Kill the RDB file without errors

sometimes you just wanna kill the RDB-saving child process without generating an error. relatable. you can do this using the signal SIGUSR1.

this signal is handled in a special way: it kills the child process like any other signal, but the parent process will not detect this as a critical error and will continue to serve write requests. the icon behavior we deserve. ✨

---

🌈 vibe check summary: SIGTERM/SIGINT = graceful shutdown, SIGSEGV/SIGBUS/SIGFPE/SIGILL = crash handling, child death = error states, SIGUSR1 = kill the RDB child with zero drama. that's the whole page, bestie. you ate. 🍓

---

and that's a wrap on this lil manual page 🦋 — it's from the Valkey manual, version 9.0.0, dated 2025-10-21. go forth and signal responsibly, queen 👑💜