CLUSTER-NODES(3valkey)

📦

version 9.0.6 · 2 versions

9.0.6 · fedora 44 (latest)
8.1.10 · fedora 43

💖 CLUSTER-NODES 💖

hey bestie, welcome to the Valkey Command Manual page for cluster-nodes — yes it's a 3valkey page, and yes it's about to be your new fave 🫶

🎀 NAME

cluster-nodes — returns the cluster configuration for a node. that's it, that's the whole job 💅

🌸 SYNOPSIS

CLUSTER NODES

✨ DESCRIPTION

so every single node in a Valkey Cluster has its own lil view of what the cluster currently looks like — that means the set of nodes it knows about, the state of the connection it has with each of those nodes, their flags, their properties, the slots assigned to them, and honestly just… all of it 🦋

CLUSTER NODES hands you all of that information — the current cluster configuration of whichever node you happen to be talking to — in a serialization format that is literally exactly the same as the one Valkey Cluster itself uses to store the cluster state on disk. (okay, tiny caveat: the on-disk version has a few extra bits of info appended at the end 🙈)

ngl, if you're a client and all you want is the map between Cluster hash slots and node addresses, you should be using valkey-cluster-slots(7) CLUSTER SLOTS instead. CLUSTER NODES gives you more, so it's the one you want for administrative tasks, debugging, and configuration inspections. valkey-cli uses it too, to manage a cluster. iykyk 💜

📜 Serialization format

the output is just a space-separated CSV string, where each line = one node in the cluster. here's what it looks like on Valkey 7.2.4:

07c37dfeb235213a872192d90877d0cd55635b91 127.0.0.1:30004@31004,hostname4 slave e7d1eecce10fd6bb5eb35b9f99a514335d9ba9ca 0 1426238317239 4 connected
67ed2db8d677e59ec4a4cefb06858cf2a1a89fa1 127.0.0.1:30002@31002,hostname2 master - 0 1426238316232 2 connected 5461-10922
292f8b365bb7edb5e285caf0b7e6ddc7265d2f4f 127.0.0.1:30003@31003,hostname3 master - 0 1426238318243 3 connected 10923-16383
6ec23923021cf3ffec47632106199cb7f496ce01 127.0.0.1:30005@31005,hostname5 slave 67ed2db8d677e59ec4a4cefb06858cf2a1a89fa1 0 1426238316232 5 connected
824fe116063bc5fcf9f4ffd895bc17aee7731ac3 127.0.0.1:30006@31006,hostname6 slave 292f8b365bb7edb5e285caf0b7e6ddc7265d2f4f 0 1426238317741 6 connected
e7d1eecce10fd6bb5eb35b9f99a514335d9ba9ca 127.0.0.1:30001@31001,hostname1 myself,master - 0 0 1 connected 0-5460

each line is made of these fields:

<id> <ip:port@cport[,hostname]> <flags> <master> <ping-sent> <pong-recv> <config-epoch> <link-state> <slot> <slot> ... <slot>

and here's what each field actually means, bestie, no cap:

id: the node ID — a 40-character globally unique string, generated when a node is created and never changed again (unless valkey-cluster-reset(7) CLUSTER RESET HARD is used 👀).
ip:port@cport: the node address clients should contact to run queries, plus the cluster bus port that's in use. you can expect :0@0 when the address is no longer known for this node ID — that's when it gets flagged with noaddr. heads up: ip can be an IPv6 address, which can contain multiple colons. here, an IPv6 address is not wrapped in square brackets like it would be in other contexts (URIs, for example). so to properly split the ip:port@cport into ip and port@cport, you need to find the last colon 🧐
hostname: a human readable string, configurable via the cluster-annouce-hostname setting. max length is 256 characters, not counting the null terminator. it can only contain ASCII alphanumeric characters, -, and ..
flags: a comma-separated list of flags: myself, master, slave, fail?, fail, handshake, noaddr, nofailover, noflags. explained below ⬇️
master: if the node is a replica and the primary is known, this is the primary node ID. otherwise it's the - character.
ping-sent: Unix time at which the currently active ping was sent, in milliseconds — or zero if there are no pending pings.
pong-recv: Unix time the last pong was received, in milliseconds.
config-epoch: the configuration epoch (or version) of the current node — or of the current primary if the node is a replica. every time there's a failover, a brand new, unique, monotonically increasing configuration epoch is created ✨. if multiple nodes claim to serve the same hash slots, the one with the higher configuration epoch wins 👑
link-state: the state of the link used for the node-to-node cluster bus. use this link to communicate with the node. it can be connected or disconnected.
slot: a hash slot number or range. it starts from argument number 9, and there may be up to 16384 entries in total (a limit that's never reached, lbr). this is the list of hash slots served by this node. if the entry is just a number, it's parsed as such. if it's a range, it's in the form start-end, and it means the node is responsible for all the hash slots from start to end, inclusive of both the start and end values.

the flags are:

myself: the node you are contacting.
master: node is a primary.
slave: node is a replica.
fail?: node is in PFAIL state. not reachable for the node you are contacting, but still logically reachable (so, not in FAIL state).
fail: node is in FAIL state. it was not reachable for multiple nodes, which promoted the PFAIL state to FAIL.
handshake: untrusted node, we are handshaking 🤝
noaddr: no address known for this node.
nofailover: replica will not try to failover.
noflags: no flags at all. iconic minimalism 💅

💌 REPLY

valkey-protocol(7) Bulk string reply: the serialized cluster configuration.

⚡ COMPLEXITY

O(N) where N is the total number of Cluster nodes

🔐 ACL CATEGORIES

@slow

🕰️ HISTORY

Available since: 3.0.0

📡 Notes on published config epochs

replicas broadcast their primary's config epochs (this is so they get an UPDATE message if they're found to be stale). that means the real config epoch of the replica — which is more or less meaningless anyway, since replicas don't serve hash slots — can only be obtained by checking the node flagged as myself, which is the entry of the node we're asking to generate the CLUSTER NODES output. the other replicas' epochs reflect what they publish in heartbeat packets, which is: the configuration epoch of the primaries they're currently replicating 💖

🌀 Special slot entries

normally, the hash slots associated with a given node are in one of these formats, as already explained up above:

Single number: 3894
Range: 3900-4000

but sometimes node hash slots can be in a special state — used to communicate errors after a node restart (a mismatch between the keys in the AOF/RDB file and the node hash slots configuration), or when a resharding operation is in progress. these two states are importing and migrating.

the meaning of both states is explained in valkey-cluster-spec(7) Valkey Specification, but the gist is this:

Importing slots are not yet part of the node's hash slots — there's a migration in progress. the node will only accept queries about these slots if the ASK command is used.
Migrating slots are assigned to the node, but they're being migrated to some other node. the node will accept queries if all the keys in the command already exist, otherwise it emits what's called an ASK redirection, to force new keys to be created directly in the importing node.

importing and migrating slots show up in the CLUSTER NODES output like this:

Importing slot: [slot_number-<-importing_from_node_id]
Migrating slot: [slot_number->-migrating_to_node_id]

here are a few examples of importing and migrating slots:

[93-<-292f8b365bb7edb5e285caf0b7e6ddc7265d2f4f]
[1002-<-67ed2db8d677e59ec4a4cefb06858cf2a1a89fa1]
[77->-e7d1eecce10fd6bb5eb35b9f99a514335d9ba9ca]
[16311->-292f8b365bb7edb5e285caf0b7e6ddc7265d2f4f]

note that the format has no spaces in it, so the CLUSTER NODES output format is plain CSV with space as separator, even when these special slots get emitted. that said, a complete parser for the format should be able to handle them 🧚

and also note that:

Migration and importing slots are only added to the node flagged as myself. this information is local to a node, for its own slots.
Importing and migrating slots are provided as additional info. if the node has a given hash slot assigned, it will also appear as a plain number in the list of hash slots — so clients that have no clue about hash slot migrations can just skip these special fields 🙈

NOTE: if not for backward compatibility, the Valkey project no longer uses the words "master" and "slave". unfortunately, in the given commands these words are part of the protocol, so we'll only be able to remove such occurrences when this API is naturally deprecated. 💀

and that's a wrap, bestie 🎀 this lil page is from version 9.0.0, dated 2025-10-21 — go forth and inspect your cluster, you absolute main character 👑💖

📦 where this page comes from

fedora 44: valkey-doc 9.0.3-2.fc44 · CC-BY-SA-4.0
fedora 44: valkey-doc 9.0.6-1.fc44 · CC-BY-SA-4.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms