nodetool move

Moves the node to a new token position in the ring.

Synopsis

nodetool [connection_options] move <new_token>

See connection options for connection options.

Description

nodetool move reassigns a node's token position in the cluster ring. This causes the node to stream data to/from other nodes to match its new token ownership. Moving a token changes which data the node is responsible for.

Disruptive Operation

Moving a node causes significant data streaming and temporarily affects cluster performance. Plan carefully and execute during maintenance windows.

Single Token Only

This command only works with single-token nodes. Clusters using vnodes (virtual nodes, the modern default) cannot use this command.

Arguments

Argument	Description
`new_token`	The new token value for this node

Examples

Move to New Token

nodetool move 1234567890

Prerequisites

Single Token Configuration

This command requires single-token configuration:

num_tokens: 1
initial_token: <token_value>

Not Compatible with vnodes

If using vnodes (num_tokens > 1), you'll see:

Error: Cannot move a node with vnodes

When to Use

Rebalancing Token Ring

To redistribute data more evenly:

# Check current token distribution
nodetool ring

# Calculate new token for better distribution
# Move node to new position
nodetool move <calculated_token>

Correcting Token Placement

After incorrect initial token assignment:

# View current token
nodetool info | grep Token

# Move to correct position
nodetool move <correct_token>

Process Flow

Token Move Process:

1. Execute move command
2. Node calculates new token ranges
3. Streams out data no longer owned
4. Streams in data now owned
5. Updates token in gossip
6. Move complete

Monitoring

During Move

# Watch streaming progress
watch -n 5 'nodetool netstats'

# Check node status
nodetool status

Verify Completion

# Check new token
nodetool info | grep Token

# Verify ring
nodetool ring

Impact Assessment

Aspect	Impact
Disk I/O	High (streaming)
Network	High (data transfer)
CPU	Moderate
Query latency	May increase during move
Duration	Minutes to hours

Troubleshooting

Move Fails with vnodes

Error: Cannot move a node with vnodes

Cannot use move with vnodes. For vnode clusters, use nodetool decommission and add new node, or use nodetool rebuild.

Move Interrupted

# Check streaming status
nodetool netstats

# Node may be in inconsistent state
# May need to decommission and rejoin

Data Inconsistency After Move

# Run repair after move completes
nodetool repair -pr

Best Practices

Move Guidelines

Plan token values - Calculate optimal distribution
Maintenance window - Perform during low traffic
Monitor streaming - Watch netstats during move
Repair after - Run repair to ensure consistency
One at a time - Move one node before starting another

Considerations

Only works with single-token configuration
High network and disk impact
May take extended time for large datasets
Consider decommission/add instead for major changes

Token Calculation

Even Distribution Formula

For N nodes with single tokens:

Token for node i = (i * (2^63 * 2)) / N

Example: 4 Node Cluster

Node 0: 0
Node 1: 4611686018427387904
Node 2: 9223372036854775808
Node 3: 13835058055282163712

Command	Relationship
ring	View token ring
info	View node's current token
decommission	Remove node from cluster
netstats	Monitor streaming
status	View cluster status