Consistent hashing is a key-to-node mapping technique that places both servers and request keys on the same circular hash space, so that each key is served by the next node clockwise on the ring. In load balancing and wider networking, it lets a balancer send the same client, session or object to the same backend while ensuring that a change in the server pool remaps only about 1/n of the keys instead of nearly all of them.
The technique was introduced for distributed web caching in the late 1990s and is now built into proxy load balancers, content delivery networks, distributed caches and key-value stores. It is the main alternative to simple modulo hashing, which breaks affinity for almost every key whenever the number of servers changes.
How the hash ring assigns keys to servers
A consistent hashing scheme starts with a fixed hash space, typically the range of a 32-bit or 64-bit hash function, treated as a circle whose end wraps around to its start. Each backend server is hashed, usually from its name or address, to one or more positions on the ring. Each incoming key, such as a source IP address, a URI or a session cookie, is hashed with the same function to its own position.
The balancer then walks clockwise from the key position and selects the first server token it meets. Because each server owns only the arc between its predecessor and itself, removing that server hands its arc to the next neighbor on the ring, and every other assignment stays where it was. Adding a server splits one existing arc in the same way.
The steps below summarize the lookup path inside a typical implementation.
- Hash every server identifier, often many times, into tokens on the ring.
- Store the tokens in a sorted array or tree for fast search.
- Hash the request key with the same function.
- Find the first token greater than or equal to the key hash with a binary search, wrapping to the first token if none is found.
- Forward the request to the server that owns that token, or to the next healthy one.
The lookup cost is O(log n) in the number of tokens, which is negligible compared with network latency. The real engineering effort goes into keeping the token table identical on every balancer instance so that all of them route a key the same way.
Virtual nodes, weights and balance
With only one token per server, the arcs on the ring have very uneven lengths, and some servers receive several times the average load. Implementations therefore place many virtual nodes per server, commonly 100 to several hundred tokens, which pulls each server share close to the mean. Virtual nodes also make weighting straightforward: a server with twice the capacity receives twice as many tokens.
The table below lists the parameters that most strongly affect how evenly a consistent hashing ring distributes traffic.
| Parameter | Typical setting | What it affects |
|---|---|---|
| Virtual nodes per server | 100-200 tokens | Load spread and memory for the token table |
| Hash function | MurmurHash, xxHash, CRC32 | Uniformity and lookup speed |
| Hash key | Source IP, URI, header or cookie | What stays pinned to one server |
| Server weight | Proportional token count | Share of traffic per backend |
| Bounded load factor | 1.25 times the average | Maximum overload before spilling to the next node |
Even with virtual nodes, a ring cannot correct for skewed key popularity. If one URI receives a fifth of all requests, the server owning it carries that fifth no matter how evenly the arcs are cut. The variant called consistent hashing with bounded loads addresses this by capping each server at a configurable multiple of the average and forwarding excess keys clockwise to the next node with spare capacity.
Consistent hashing compared with other balancing methods
Consistent hashing belongs to the family of hash-based load balancing algorithms, and its value becomes clear only next to its neighbors. The following comparison shows how it differs from stateless and modulo-based methods.
| Method | Key affinity | Keys remapped when a server changes | Typical use |
|---|---|---|---|
| Round robin | None | Not applicable | Stateless web and API tiers |
| Least connections | None | Not applicable | Long-lived or uneven requests |
| IP hash with modulo | Per client address | Nearly all keys | Small, fixed server pools |
| Consistent hashing | Per chosen key | About 1/n of keys | Caches, sharded stores, sticky routing |
| Rendezvous hashing | Per chosen key | About 1/n of keys | Small pools needing no token table |
| Maglev hashing | Per connection or flow | Small, slightly above 1/n | High-speed Layer 4 balancers |
Unlike a sticky session based on a cookie, consistent hashing needs no stored state on the balancer: any instance computes the same answer from the key alone. That makes it attractive for clusters of balancers behind equal-cost multipath routing, where a client flow may reach a different balancer after a routing change. Rendezvous hashing, also called highest random weight, achieves the same minimal disruption by scoring every server for every key, which is simpler but costs O(n) work per lookup.
Where consistent hashing is used in practice
The method fits any workload where sending a key to the same server saves work. Cache hit ratios, local session data and sharded data placement all benefit, while purely stateless services gain little and lose some balance. The decision table below summarizes common situations.
| Situation | Recommended choice | Reason |
|---|---|---|
| Reverse proxy cache cluster | Hash on the request URI | Each object is cached once, which raises the hit ratio |
| Distributed key-value store | Hash on the record key | Data placement survives node changes |
| Stateful application sessions | Hash on a session cookie | Session data stays local without a shared store |
| Stateless REST API | Prefer least connections | Affinity adds imbalance without any benefit |
| Clients behind carrier-grade NAT | Avoid hashing on source IP | Thousands of users share one address |
In HAProxy, the hash-type consistent directive turns hash-based balancing such as balance uri or balance source into ring-based selection. NGINX offers the hash $request_uri consistent form inside an upstream block, and Envoy provides the ring hash and Maglev load balancers. Distributed databases such as Cassandra and DynamoDB-style systems use the same principle to place data partitions across nodes, often combined with replication to the next nodes clockwise.
Limitations and common mistakes
Consistent hashing reduces disruption but never eliminates it, and several operational errors undo its benefits. The most frequent problems are listed below together with their causes and fixes.
| Symptom | Likely cause | Fix |
|---|---|---|
| One backend runs far hotter than others | Too few virtual nodes | Raise the token count per server |
| Hot spot persists after rebalancing | Popular key concentration | Enable bounded loads or cache hot keys |
| Keys move between balancer instances | Inconsistent server lists | Distribute an identical, ordered pool definition |
| Mass cache misses after a deploy | Server identifiers changed | Hash stable names, not ephemeral addresses |
| Failed node overloads its neighbor | Load shifts to one successor | Use virtual nodes so load spreads to many peers |
A subtle failure mode is health check flapping. Each time an unstable server leaves and rejoins the ring, its keys move away and back, so caches warm twice and sessions break twice. Dampening health checks, combined with connection draining before planned removals, keeps the ring stable. Operators should also remember that hashing on a source IP address behaves poorly when many users share one public address, because the affinity unit is the address, not the user.
The simple explanation
Imagine a round clock face where every server is pinned at a few spots around the edge. Each request also gets a spot on the clock, decided by a fixed calculation, and it is handed to the next server you reach going clockwise.
If one server leaves, only the requests that pointed to its spots slide forward to the next server. Everyone else keeps the same server as before. That is the whole idea: a change in the team disturbs only a small slice of the work, so caches stay useful and users keep their sessions.
How it is used in practice
A video platform runs a tier of 12 caching proxies in front of its storage, with a pair of HAProxy balancers distributing requests by URI. With plain modulo hashing, adding a thirteenth proxy during an evening peak would have remapped roughly 92 percent of URIs, sending a wave of cache misses to the storage back end.
After the team switched to consistent hashing with 150 virtual nodes per proxy and a bounded load factor of 1.25, adding the new proxy moved only about one thirteenth of the URIs. Storage request volume rose briefly by a few percent instead of multiplying, and the busiest proxy stayed within a quarter of the average load. The outcome was a scale-out during peak traffic without a cache miss storm.