Non-atomic check-then-act on a ConcurrentHashMap

What this error actually means

A `ConcurrentHashMap` guarantees that each individual operation is atomic and that the map’s internal state never corrupts. It guarantees nothing about a *sequence* of operations you perform on it. `get`, then decide, then `put` is three atomic operations with two gaps, and another thread can complete its own full sequence inside either gap.

The distinction is between the map being thread-safe and your *compound action* being thread-safe. Thread safety is not a property that composes: two atomic operations placed next to each other are not atomic together, and no amount of concurrency in the collection can make them so, because the map cannot see the invariant that spans them.

What makes `compute`, `computeIfAbsent`, `merge`, `putIfAbsent`, and `replace` different is that they perform the whole read-modify-write while holding the lock on the map’s internal bin for that key. The map does not just do two operations for you — it does them without releasing the per-bin lock in between, so no other thread can observe or modify that key mid-sequence. That is an atomicity guarantee your code cannot construct from the outside, which is precisely why these methods exist.

There is no exception here either. The lost-update form loses data silently: a counter that reads low, a set of accumulated items missing entries, a status field that reverts. The duplicate-creation form is louder only by accident — you notice it when the object being created has a side effect that complains, such as a metric registration that rejects duplicates or a connection that logs on open.

How to diagnose it

var latch = new CountDownLatch(1);
IntStream.range(0, 8).forEach(i -> new Thread(() -> {
    await(latch);
    for (int j = 0; j < 50_000; j++) bump(map, "k");
}).start());
latch.countDown();

grep -rn -E "\.put\([^,]+, *[a-zA-Z_]+\.get\(|containsKey\(" src/main/java | grep -v test

grep "creating session" app.log | awk '{print $NF}' | sort | uniq -c | awk '$1 > 1'

grep -n "IllegalStateException: Recursive update" app.log

The fix

Replace the sequence with the single atomic operation that expresses it. `merge(k, 1, Integer::sum)` for accumulation, `compute(k, (key, old) -> …)` for a general read-modify-write, `computeIfAbsent(k, loader)` for create-if-absent, `replace(k, expected, updated)` when you need compare-and-set on a key. Each performs the whole update under the bin lock, so no gap exists for another thread to occupy.

For counters specifically, prefer `LongAdder` values over boxed `Integer` and arithmetic: `map.computeIfAbsent(k, x -> new LongAdder()).increment()`. The `computeIfAbsent` is atomic for creation, and `LongAdder` handles the increment with striped counters that scale far better than a contended CAS on a shared cell.

Keep the mapping function short, side-effect-free, and free of any access to the same map. It runs while the bin lock is held, so a slow function blocks every other operation on that key’s bin, and touching the same map can deadlock or throw `IllegalStateException: Recursive update`. If the value is expensive to build, store a `CompletableFuture` or a memoising `Future` as the value and let callers await it outside the lock.

Make map values immutable, and replace rather than mutate. `compute(k, (key, old) -> old.withItem(x))` is atomic and safe; `get(k).add(x)` is neither. If a value must be a mutable collection, make it a concurrent one and be explicit that the map protects the *mapping* and not the contents.

Never use `size()`, `isEmpty()`, or iteration as a decision input under concurrent writes. When you need a bound, enforce it with a structure designed for it — a `Semaphore` for admission, or a cache library with a size policy — rather than checking a count that is stale the instant you read it.

When the invariant spans two keys or two maps, per-key atomicity is insufficient and you need a lock around the whole transition, or a redesign that puts the co-varying fields in one immutable value under one key. This is the one case where reaching for a lock is the right answer rather than a failure of imagination.

// Loses updates: three operations, two gaps
Integer current = counts.get(key);
counts.put(key, current == null ? 1 : current + 1);

// Duplicates the value, and its side effects, under a race
if (!sessions.containsKey(tenant)) {
    sessions.put(tenant, openSession(tenant));   // both threads open a session
}

// Atomic accumulation: whole update under the bin lock
counts.merge(key, 1L, Long::sum);

// Atomic create-if-absent: the function runs at most once per key
Session s = sessions.computeIfAbsent(tenant, this::openSession);

// High-contention counters scale better with striped adders
counts.computeIfAbsent(key, k -> new LongAdder()).increment();

// Atomic read-modify-write on an immutable value
baskets.compute(userId, (k, old) ->
    (old == null ? Basket.empty() : old).withLine(line));

How to stop it coming back

• Treat `get`-then-`put` and `containsKey`-then-`put` on a concurrent map as defects on sight; there is always an atomic method that replaces them
• Prefer immutable map values and whole-value replacement so no code path can mutate a shared value outside the map’s atomicity
• Add a contended-update test for every counter or accumulator: N threads, fixed increments, exact expected total
• Keep mapping functions pure and fast — never perform I/O, acquire another lock, or touch the same map inside one
• Never base control flow on `size()` or iteration of a concurrently modified map; they are documented as approximate for exactly this reason
• Where creation has side effects, make the creation path unmistakably single-shot via `computeIfAbsent`, and log a warning if a second creation for the same key ever occurs

FAQ

Related

Other errors engineers hit next to this one

• Text file busy during executable replacement
• set -e script continues after a failed pipeline
• An unquoted variable turns one argument into several
• 502 Bad Gateway from a reverse proxy
• 504 Gateway Timeout
• CORS preflight: missing Access-Control-Allow-Origin
• 413 Payload Too Large
• 429 Too Many Requests and Retry-After