nodetool truncatehints

Removes all pending hints from this node.

Synopsis

nodetool [connection_options] truncatehints [endpoint]

See connection options for connection options.

Description

nodetool truncatehints deletes stored hints on this node. Hints are writes stored temporarily when a replica is unavailable, to be replayed when the replica recovers. Truncating hints discards these pending writes.

Arguments

Argument	Description
`endpoint`	Optional. Only truncate hints for this specific endpoint IP

Examples

Truncate All Hints

nodetool truncatehints

Truncate Hints for Specific Node

nodetool truncatehints 192.168.1.105

When to Use

Node Permanently Removed

When a node is removed and won't return:

# After removing node 192.168.1.105
nodetool truncatehints 192.168.1.105

Hints for removed nodes will never be delivered.

Hint Backlog Too Large

When hints have accumulated excessively:

# Check hint status
nodetool tpstats | grep -i hint

# If backlog is causing issues
nodetool truncatehints

Replace Node Scenario

When replacing a node (new node, same IP):

# Truncate hints for the old node
nodetool truncatehints 192.168.1.105

# Then add replacement node

When NOT to Use

Data Loss Warning

Truncating hints means:

Pending writes will NOT be delivered
Data may become inconsistent
Only use when recovery isn't possible or desired

Don't Use When

Node is temporarily down and will recover
You want to preserve data consistency
During normal operations

Understanding Hints

What Hints Contain

When a write fails to reach a replica:

Coordinator stores the write as a "hint"
Hint includes: mutation data + target endpoint
When target recovers, hints are replayed

Hint Location

Hints are stored in:

/var/lib/cassandra/hints/

Check Pending Hints

# See hint delivery status
nodetool tpstats | grep -i hint

# List hint files
ls -la /var/lib/cassandra/hints/

Impact of Truncation

Scenario	Impact
Target node returns	Missed writes not recovered (run repair)
Target node replaced	Old hints not needed anyway
Target node removed	Hints would never deliver

Recovery After Truncation

If hints are truncated but data consistency is needed:

# Run repair to restore consistency
nodetool repair -pr keyspace

Hint Configuration

Related settings in cassandra.yaml:

Setting (4.1+)	Setting (Pre-4.1)	Default	Description
`max_hint_window`	`max_hint_window_in_ms`	3h / 10800000	Stop hinting after this duration
`hinted_handoff_enabled`	`hinted_handoff_enabled`	true	Whether hints are created
`hints_directory`	`hints_directory`	`$DATA/hints`	Hint storage location

Workflow: Decommission with Hints

# 1. Check if node has pending hints
nodetool tpstats | grep -i hint

# 2. If removing node permanently, truncate its hints
nodetool truncatehints <removed_node_ip>

# 3. Run repair to ensure consistency
nodetool repair -pr

Monitoring Hints

Before Truncation

# Check hint backlog
nodetool tpstats | grep HintedHandoff

# Check hint files size
du -sh /var/lib/cassandra/hints/

After Truncation

# Verify hints removed
ls -la /var/lib/cassandra/hints/

# Confirm empty
nodetool tpstats | grep HintedHandoff

Common Scenarios

Scenario 1: Long-Down Node

Node has been down for days:

# Check hints accumulated
du -sh /var/lib/cassandra/hints/

# If node won't return, truncate
nodetool truncatehints 192.168.1.105

# Run repair on recovered node instead

Scenario 2: Hint Disk Full

Hints filling disk:

# Emergency truncation
nodetool truncatehints

# Then run repairs
nodetool repair -pr

Scenario 3: Node Replacement

Replacing dead node with new hardware:

# Truncate hints for old node
nodetool truncatehints 192.168.1.105

# Bootstrap new node with same tokens
# Run repair after bootstrap

Best Practices

Hint Management

Prefer repair over truncation - Repair recovers data properly
Truncate only for removed nodes - Hints to removed nodes are useless
Monitor hint growth - Large hint backlogs indicate problems
Repair after truncation - Restore consistency
Consider max_hint_window - Tune to match your SLA

Command	Relationship
tpstats	Check hint delivery status
repair	Restore consistency after truncation
removenode	Remove dead nodes (truncate hints after)
decommission	Graceful node removal