CLIENT-KILL(3valkey)

📦
version 9.0.6 · 2 versions
, in fedora 44

✨ NAME ✨

client-kill — terminates open connections 💀 (it's in the 3valkey manual, bestie)

🌸 SYNOPSIS 🌸

CLIENT KILL ip:port
CLIENT KILL [<ID client-id [client-id...]  | TYPE <NORMAL | MASTER |
PRIMARY | SLAVE | REPLICA | PUBSUB> | USER username | ADDR ip:port |
LADDR ip:port | SKIPME <YES | NO> | MAXAGE maxage | NAME name | IDLE
idle | FLAGS flags | LIB-NAME lib-name | LIB-VER lib-ver | DB db | CAPA
capa | IP ip | NOT-TYPE <NORMAL | MASTER | PRIMARY | SLAVE | REPLICA |
PUBSUB> | NOT-ID not-client-id [not-client-id...]  | NOT-USER
not-username | NOT-ADDR ip:port | NOT-LADDR ip:port | NOT-NAME not-name
| NOT-FLAGS not-flags | NOT-LIB-NAME not-lib-name | NOT-LIB-VER
not-lib-ver | NOT-DB not-db | NOT-CAPA not-capa | NOT-IP not-ip>...]

💅 DESCRIPTION 💅

okay so CLIENT KILL closes a given client connection. simple as that. it's giving "you're done here, bestie, bye 👋". and it supports two formats: the old one and the new one.

The old format, a.k.a. the vintage era:

CLIENT KILL addr:port

The ip:port should match a line returned by the CLIENT LIST command (the addr field). that's the OG way, no cap.

The new format, a.k.a. the glow-up ✨:

CLIENT KILL <filter> <value> ... ... <filter> <value>

With the new form it is possible to kill clients by different attributes instead of killing just by address. it's so versatile, honestly iconic. The following filters are available:

  • CLIENT KILL ADDR ip:port — This is exactly the same as the old three-arguments behavior. same energy, new syntax.
  • CLIENT KILL LADDR ip:port — Kill all clients connected to specified local (bind) address. local girlies only 📍
  • CLIENT KILL ID client-id [client-id ...] — Allows to kill a client by its unique ID field. Client ID's can be retrieved using the CLIENT LIST command. The filter supports one or more client-id arguments. bring the whole crew, it handles it.
  • CLIENT KILL TYPE type — where type is one of normal, master, replica and pubsub. This closes the connections of all the clients in the specified class. Note that clients blocked into the MONITOR command are considered to belong to the normal class. periodt.
  • CLIENT KILL USER username — Closes all the connections that are authenticated with the specified valkey-acl(7) username, however it returns an error if the username does not map to an existing ACL user. no user, no service 😭
  • CLIENT KILL SKIPME yes/no — By default this option is set to yes, that is, the client calling the command will not get killed, however setting this option to no will have the effect of also killing the client calling the command. main character sacrifice 🫡
  • CLIENT KILL MAXAGE maxage — Closes all the connections that are older than the specified age, in seconds. it's giving "you're too old for this app".
  • CLIENT KILL FLAGS flags — Kill only clients whose flag string includes the specified characters. Returns an error if valid flags are not used. 🚩
  • CLIENT KILL NAME name — Kill clients with the specified name. called them out by name fr fr.
  • CLIENT KILL IDLE idle — Kill only clients that have been idle for at least the specified time. the lurkers are getting removed 💀
  • CLIENT KILL LIB-NAME lib-name — Kill clients using the specified library name.
  • CLIENT KILL LIB-VER lib-version — Kill clients running the specified library version.
  • CLIENT KILL DB db — Kill clients operating on the specified database id.
  • CLIENT KILL IP ip — Kill clients with the specified originating IP address.
  • CLIENT KILL CAPA capa — Kill clients that have the specified capabilities.
  • CLIENT KILL NOT-ID client-id [client-id ...] — Kill clients are not in the IDs set.
  • CLIENT KILL NOT-TYPE type — Kill clients are not in the specified type.
  • CLIENT KILL NOT-ADDR ip:port — Kill clients except the specified ip and port.
  • CLIENT KILL NOT-LADDR ip:port — Kill all clients not connected to specified local (bind) address.
  • CLIENT KILL NOT-USER username — Closes all the connections that are not authenticated with the specified valkey-acl(7) username.
  • CLIENT KILL NOT-FLAGS flags — Kill clients not with the specified flag string.
  • CLIENT KILL NOT-NAME name — Kill clients not with the specified name.
  • CLIENT KILL NOT-LIB-NAME lib-name — Kill clients not using the specified library name.
  • CLIENT KILL NOT-LIB-VER lib-version — Kill clients not with the specified library version.
  • CLIENT KILL NOT-DB db — Kill clients not with the specified database ID.
  • CLIENT KILL NOT-CAPA capa — Kill clients not with the specified capabilities.
  • CLIENT KILL NOT-IP ip — Kill clients not with the specified IP address.

It is possible to provide multiple filters at the same time. The command will handle multiple filters via logical AND. For example:

CLIENT KILL addr 127.0.0.1:12345 type pubsub

is valid and will kill only a pubsub client with the specified address. This format containing multiple filters is rarely useful currently. (they're just being honest, lowkey.)

When the new form is used the command no longer returns OK or an error, but instead the number of killed clients, that may be zero. yes, zero. sometimes nobody gets killed and that's okay 🌸

🧚 CLIENT KILL and Valkey Sentinel 🧚

Valkey Sentinel uses CLIENT KILL to terminate client connections when an instance is reconfigured. This mechanism ensures that clients re-establish a connection with a Sentinel, refreshing their configurations. it's a whole system, bestie. it's giving coordinated.

🔥 REPLY 🔥

One of the following:

  • valkey-protocol(7) Simple string reply: OK when called in 3 argument format and the connection has been closed.
  • valkey-protocol(7) Integer reply: when called in filter/value format, the number of clients killed.

⭐ COMPLEXITY ⭐

O(N) where N is the number of client connections

👑 ACL CATEGORIES 👑

@admin @connection @dangerous @slow

🦋 HISTORY 🦋

  • Available since: 2.4.0
  • Changed in 2.8.12: Added new filter format.
  • Changed in 2.8.12: ID option.
  • Changed in 3.2.0: Added master type in for TYPE option.
  • Changed in 5.0.0: Replaced slave TYPE with replica. slave still supported for backward compatibility.
  • Changed in 6.2.0: LADDR option.
  • Changed in 8.0.0: MAXAGE option.
  • Changed in 8.0.0: Replaced master TYPE with primary. master still supported for backward compatibility.
  • Changed in 8.1.0: ID option accepts multiple IDs.
  • Changed in 9.0.0: Added filters NAME, IDLE, FLAGS, LIB-NAME, LIB-VER, DB, CAPA, and IP. And negative filters NOT-ID, NOT-TYPE, NOT-ADDR, NOT-LADDR, NOT-USER, NOT-FLAGS, NOT-NAME, NOT-LIB-NAME, NOT-LIB-VER, NOT-DB, NOT-CAPA, NOT-IP.

💀 NOTES 💀

Due to the single-threaded nature of Valkey, it is not possible to kill a client connection while it is executing a command. From the client point of view, the connection can never be closed in the middle of the execution of a command. However, the client will notice the connection has been closed only when the next command is sent (and results in network error).

ngl this is the important bit: you can't yank the connection mid-command, and the client won't even know until it sends the next one and gets a network error. it's giving "left on read but the read never happened yet" 😭

🌈 SEE ALSO 🌈

auth(3valkey), client(3valkey), client-caching(3valkey), client-capa(3valkey), client-getname(3valkey), client-getredir(3valkey), client-help(3valkey), client-id(3valkey), client-import-source(3valkey), client-info(3valkey), client-list(3valkey), client-no-evict(3valkey), client-no-touch(3valkey), client-pause(3valkey), client-reply(3valkey), client-setinfo(3valkey), client-setname(3valkey), client-tracking(3valkey), client-trackinginfo(3valkey), client-unblock(3valkey), client-unpause(3valkey), echo(3valkey), hello(3valkey), ping(3valkey), quit(3valkey), reset(3valkey), select(3valkey)

okay that's the whole page bestie, you ate that 💅 this was 9.0.0, dated 2025-10-21, straight out of the 3valkey manual — ily, go kill some connections responsibly 🫶✨

📦 where this page comes from