Why ThreadLocal and ConcurrentHashMap Aren’t the Silver Bullet for Thread Safety

ThreadLocal Pitfall: Your Data Gets Shared!

Many developers assume that using ThreadLocal guarantees isolated data per thread, but in a thread‑pooled web server this assumption can break, leading to unexpected data sharing.

1.1 Problem Reproduction

A test case shows that a request handled by Tomcat sometimes returns the previous user's data because the same thread is reused.

@RestController
@RequestMapping("/threadlocal")
public class ThreadLocalController {
    private static final ThreadLocal<Integer> currentUser = ThreadLocal.withInitial(() -> null);
    @GetMapping("/wrong")
    public Map<String, String> wrong(@RequestParam("userId") Integer userId) {
        String before = Thread.currentThread().getName() + ":" + currentUser.get();
        currentUser.set(userId);
        String after = Thread.currentThread().getName() + ":" + currentUser.get();
        Map<String, String> result = new HashMap<>();
        result.put("before", before);
        result.put("after", after);
        return result;
    }
}

Running this on Tomcat with a single‑thread pool ( server.tomcat.max-threads=1) reproduces the issue: the first request returns before=null, after=1, while the second request returns before=1, after=2, showing that the thread retained the previous ThreadLocal value.

1.2 Root Cause

Tomcat uses a thread pool; when a thread is reused, the ThreadLocal value from the previous request is still present because ThreadLocal does not automatically clear its data.

1.3 Solution: Clean ThreadLocal Data

Clear the ThreadLocal in a finally block after each request.

@GetMapping("/right")
public Map<String, String> right(@RequestParam("userId") Integer userId) {
    String before = Thread.currentThread().getName() + ":" + currentUser.get();
    currentUser.set(userId);
    try {
        String after = Thread.currentThread().getName() + ":" + currentUser.get();
        Map<String, String> result = new HashMap<>();
        result.put("before", before);
        result.put("after", after);
        return result;
    } finally {
        currentUser.remove();
    }
}

After adding the cleanup, the bug disappears and each request sees a fresh ThreadLocal value.

2. ConcurrentHashMap Pitfall: Not All Thread‑Safety Is Covered

Replacing HashMap with ConcurrentHashMap does not make compound operations atomic.

2.1 Problem Scenario

Counting user visits with a plain ConcurrentHashMap can lose updates.

public class UserVisitCounter {
    private static final ConcurrentHashMap<String, Integer> visitCountMap = new ConcurrentHashMap<>();
    public void visit(String userId) {
        Integer count = visitCountMap.get(userId);
        if (count == null) {
            visitCountMap.put(userId, 1);
        } else {
            visitCountMap.put(userId, count + 1);
        }
    }
    public int getVisitCount(String userId) {
        return visitCountMap.getOrDefault(userId, 0);
    }
    public static void main(String[] args) throws InterruptedException {
        UserVisitCounter counter = new UserVisitCounter();
        String userId = "user1";
        ExecutorService executor = Executors.newFixedThreadPool(100);
        for (int i = 0; i < 100; i++) {
            executor.submit(() -> counter.visit(userId));
        }
        executor.shutdown();
        executor.awaitTermination(1, TimeUnit.MINUTES);
        System.out.println("Visit count: " + counter.getVisitCount(userId));
    }
}

Expected result: 100 visits.

Actual result: often less than 100 (e.g., 98, 99).

2.2 Root Cause

Multiple threads read the same count value, then each writes back count + 1; the increment is not atomic, so updates are lost.

2.3 Solutions

Option 1: Use AtomicInteger

public class UserVisitCounter {
    private static final ConcurrentHashMap<String, AtomicInteger> visitCountMap = new ConcurrentHashMap<>();
    public void visit(String userId) {
        visitCountMap.computeIfAbsent(userId, k -> new AtomicInteger(0)).incrementAndGet();
    }
    public int getVisitCount(String userId) {
        return visitCountMap.getOrDefault(userId, new AtomicInteger(0)).get();
    }
}

Option 2: Use compute method

public class UserVisitCounter {
    private static final ConcurrentHashMap<String, Integer> visitCountMap = new ConcurrentHashMap<>();
    public void visit(String userId) {
        visitCountMap.compute(userId, (k, v) -> v == null ? 1 : v + 1);
    }
    public int getVisitCount(String userId) {
        return visitCountMap.getOrDefault(userId, 0);
    }
}

2.4 Summary

ConcurrentHashMap

guarantees thread‑safety for individual operations only; compound actions such as read‑modify‑write must be protected with additional synchronization, e.g., AtomicInteger or the map’s compute methods.

In backend development, always be aware of the execution thread context, clean up ThreadLocal values after use, and choose the right concurrency primitives to avoid subtle bugs.