A ThreadLocal value retained on a pooled thread

What this error actually means

A `ThreadLocal` is not scoped to your request, your transaction, or your call stack. It is scoped to the `Thread` object, and a pooled thread outlives every request it serves. Whatever you leave in it is still there when the pool hands that thread to the next caller.

The storage is a field on `Thread` itself — `threadLocals`, a `ThreadLocalMap` whose entries use a **weak** reference to the `ThreadLocal` key and a **strong** reference to the value. People read "weak" and assume the whole entry is collectable. It is not: when the key is collected the entry becomes stale, but the value is still strongly reachable from the live thread until some later `get`, `set`, or `remove` on that same thread happens to walk past the stale slot and clear it. On a thread that goes idle in a pool, that never happens.

So one missing `remove()` produces two different bugs from the same cause, and which one you notice first is luck. The **correctness** bug is data bleed: request B on the same worker sees request A’s tenant id, user principal, locale, or trace id, because the value was never cleared and B’s code path did not set it. The **memory** bug is retention: the value, and its entire reference graph, is pinned for the lifetime of the pool — and if that graph reaches a classloader, you get Metaspace growth instead of heap growth.

The severity asymmetry is worth naming. A leaked megabyte is an operational problem. A leaked security principal is a cross-tenant data exposure that your tests, which run one request at a time on a fresh thread, cannot see at all.

How to diagnose it

if (RequestContext.current() != null) {
    throw new IllegalStateException("context leaked on " + Thread.currentThread().getName());
}

jcmd <pid> GC.class_histogram | grep -E "RequestContext|ThreadLocalMap"

jcmd <pid> GC.heap_dump /tmp/tl.hprof

var pool = Executors.newFixedThreadPool(1);  // forces thread reuse

grep -c "ForkJoinPool.commonPool-worker" dump.txt

The fix

Make `remove()` unconditional. Every `set()` needs a matching `remove()` in a `finally` on the same thread, in the same method, at the same nesting level. `remove()` — not `set(null)`: setting null leaves a live entry holding a null value, so the map slot survives and the `get()` returns null in a way that is indistinguishable from "never set", which hides the next bug.

Own the boundary rather than trusting every caller. Expose the context only through a scoped helper that acquires and releases around a lambda, so no calling code can forget the cleanup. This is the single highest-value change, because it removes the failure mode instead of documenting it.

For work handed to another thread, propagate a copy explicitly and clean it up on that thread too. A wrapping `Executor` decorator that captures on submit, installs before `run`, and removes in `finally` is the only shape that survives exceptions, cancellations, and rejected tasks.

Never let a context object hold a large or long-lived graph. Put identifiers in it, not entities: a tenant id rather than a tenant, a user id rather than a loaded principal with its permission tree. Then even a genuine leak costs bytes rather than megabytes.

On Java 21 and later, prefer `ScopedValue` for request-scoped data where you can. It is bound for the duration of a dynamic scope and unbound on exit by construction, so there is no cleanup to forget and no way for a value to outlive its scope onto a pooled thread.

Avoid `InheritableThreadLocal` entirely with pools. Inheritance happens at thread creation, which for a pool is an arbitrary moment unrelated to your request boundaries, so the semantics you want are not available.

// Leaks: remove() runs only when the handler returns normally
CTX.set(RequestContext.from(request));
chain.doFilter(request, response);   // throws -> value stays on the pool thread
CTX.remove();

// Correct: cleanup is unconditional
CTX.set(RequestContext.from(request));
try {
    chain.doFilter(request, response);
} finally {
    CTX.remove();                    // not set(null): that keeps a live entry
}

// Better: the boundary owns the lifecycle, callers cannot forget it
static <T> T withContext(RequestContext c, Supplier<T> body) {
    CTX.set(c);
    try { return body.get(); } finally { CTX.remove(); }
}

// Propagating to another pool requires cleanup on that thread too
Executor tracing = task -> {
    RequestContext captured = CTX.get();
    delegate.execute(() -> {
        CTX.set(captured);
        try { task.run(); } finally { CTX.remove(); }
    });
};

How to stop it coming back

• Wrap every application executor in a decorator that clears known holders after each task and fails the build if one is dirty
• Assert an empty context after each integration test rather than only before — leaks are visible on the way out, not the way in
• Run at least one CI suite with a single-threaded pool, which turns thread-reuse bleed from a race into a deterministic failure
• Keep context objects to identifiers and primitives; treat a `ThreadLocal` holding an entity or a bean as a review blocker
• Alarm on live instance counts of context types staying flat but non-zero while traffic is idle
• On Java 21+, adopt `ScopedValue` for new request-scoped state so the cleanup obligation does not exist

FAQ

Related

Other errors engineers hit next to this one

• java.lang.OutOfMemoryError: Java heap space
• java.lang.OutOfMemoryError: Metaspace
• java.lang.OutOfMemoryError: GC overhead limit exceeded
• java.util.ConcurrentModificationException
• OutOfMemoryError: unable to create new native thread
• RejectedExecutionException: Task rejected from ThreadPoolExecutor
• FATAL: sorry, too many clients already
• Sessions stuck in "idle in transaction"