nodetool describecluster¶

Displays basic cluster information including cluster name, snitch, and schema versions.

Synopsis¶

nodetool [connection_options] describecluster

Description¶

nodetool describecluster provides high-level cluster metadata:

Cluster name
Snitch in use
Dynamic snitch settings
Schema version information
DynamicEndpointSnitch scores

This is useful for verifying cluster configuration and detecting schema disagreement.

Output Example¶

Cluster Information:
        Name: Production Cluster
        Snitch: org.apache.cassandra.locator.GossipingPropertyFileSnitch
        DynamicEndPointSnitch: enabled
        Partitioner: org.apache.cassandra.dht.Murmur3Partitioner

Stats for all nodes:
        Live: 3
        Joining: 0
        Moving: 0
        Leaving: 0
        Unreachable: 0

Data Centers:
        dc1 #Nodes: 3 #Down: 0

Database versions:
        4.1.3: [192.168.1.101, 192.168.1.102, 192.168.1.103]

Keyspaces:
        my_keyspace -> Replication class: NetworkTopologyStrategy {dc1=3}
        system_auth -> Replication class: NetworkTopologyStrategy {dc1=3}

Schema versions:
        a1b2c3d4-e5f6-7890-abcd-ef1234567890: [192.168.1.101, 192.168.1.102, 192.168.1.103]

Output Varies by Version

The exact output format varies between Cassandra versions. Some fields like "Effective Dynamic Snitch Scores" were present in older versions but may be absent in current releases.

Output Fields¶

Cluster Information¶

Field	Description
Name	Cluster name from cassandra.yaml
Snitch	Endpoint snitch class in use
DynamicEndPointSnitch	Whether dynamic snitch is enabled
Partitioner	Token partitioner class

Stats for all nodes¶

Field	Description
Live	Number of nodes in UN (Up/Normal) state
Joining	Number of nodes currently bootstrapping
Moving	Number of nodes moving tokens
Leaving	Number of nodes decommissioning
Unreachable	Number of nodes that cannot be reached

Data Centers¶

Shows each datacenter with node count and down node count.

Database versions¶

Lists Cassandra versions with the nodes running each version.

Keyspaces¶

Shows replication configuration for each keyspace.

Schema Versions¶

Shows which schema version each node has:

Schema versions:
        <schema-version-uuid>: [list of nodes]

Interpreting Results¶

Healthy Cluster¶

Schema versions:
        a1b2c3d4-e5f6-7890-abcd-ef1234567890: [192.168.1.101, 192.168.1.102, 192.168.1.103]

All nodes show the same schema version = healthy.

Schema Disagreement¶

Schema versions:
        a1b2c3d4-e5f6-7890-abcd-ef1234567890: [192.168.1.101, 192.168.1.102]
        b2c3d4e5-f6a7-8901-bcde-f12345678901: [192.168.1.103]

Schema Disagreement

Multiple schema versions indicates:

Recent schema change still propagating
Node was down during schema change
Network partition occurred

Action: Wait for propagation or investigate the mismatched node.

Resolving Schema Disagreement¶

If schema disagreement persists:

# On the disagreeing node, try reloading schema
nodetool reloadlocalschema

# If that doesn't work, restart the node
nodetool drain
sudo systemctl restart cassandra

When to Use¶

Before Schema Changes¶

# Verify all nodes agree on schema
nodetool describecluster

Don't make schema changes during disagreement.

After Schema Changes¶

# Verify schema propagated
nodetool describecluster

All nodes should show the same schema version.

Troubleshooting Performance¶

# Check dynamic snitch scores
nodetool describecluster

High scores indicate slow nodes.

Initial Set up Verification¶

# Verify cluster configuration
nodetool describecluster

Confirm cluster name and snitch are correct.

Examples¶

Basic Usage¶

nodetool describecluster

Check from Specific Node¶

ssh 192.168.1.101 "nodetool describecluster"

Monitor Schema Agreement¶

# Wait for schema agreement
while nodetool describecluster | grep -q "Schema versions:" && \
      [ $(nodetool describecluster | grep -c "^\s*[a-f0-9]") -gt 1 ]; do
    echo "Waiting for schema agreement..."
    sleep 5
done
echo "Schema agreed"

Check All Nodes¶

for node in node1 node2 node3; do
    echo "=== $node ==="
    ssh "$node" "nodetool describecluster | grep -A10 "Schema versions""
done

Common Issues¶

Multiple Schema Versions¶

Cause: Schema change didn't propagate to all nodes.

Solutions: 1. Wait - propagation can take time 2. Check if disagreeing node can reach others 3. Reload schema on disagreeing node 4. Restart disagreeing node as last resort

"UNREACHABLE" Nodes in Schema List¶

Schema versions:
        a1b2c3d4-...: [192.168.1.101, 192.168.1.102]
        UNREACHABLE: [192.168.1.103]

Node 192.168.1.103 is down or unreachable. Check with nodetool status.

Wrong Snitch Showing¶

If snitch doesn't match cassandra.yaml:

Verify configuration file
Restart node for changes to take effect
Ensure all nodes use the same snitch

Snitch Mismatch

All nodes MUST use the same snitch. Mismatched snitches cause incorrect replica selection and potential data loss.

Snitch Types¶

Snitch	Description
SimpleSnitch	Single datacenter, no rack awareness
GossipingPropertyFileSnitch	Multi-DC, uses property file
PropertyFileSnitch	Multi-DC, uses static configuration
Ec2Snitch	AWS EC2, single region
Ec2MultiRegionSnitch	AWS EC2, multiple regions
GoogleCloudSnitch	Google Cloud Platform
RackInferringSnitch	Infers from IP address

Command	Relationship
status	Node status overview
ring	Token distribution
gossipinfo	Detailed gossip state
info	Node-specific information