Understanding ThreadLocal Memory Leaks in Java and How to Prevent Them

ThreadLocal, translated as "thread‑local variable," gives each thread its own private variable, preventing thread‑safety problems caused by concurrent writes to shared data.

In Java, thread‑safety is typically addressed either by using locks (synchronized or Lock) or by employing ThreadLocal.

Using locks serializes access to shared resources, which can degrade performance, whereas ThreadLocal creates a separate instance (e.g., a SimpleDateFormat) for each thread, eliminating contention.

The article shows that when ThreadLocal is misused, especially with long‑lived thread pools, it can lead to Out‑Of‑Memory (OOM) errors because the thread’s ThreadLocalMap retains references to large objects.

To reproduce the issue, the author sets the JVM maximum heap to 50 MB (via -Xmx50m) and runs a program that stores a 10 MB object in a ThreadLocal for each task submitted to a fixed‑size thread pool. After about five tasks, the heap is exhausted and an OOM occurs.

import java.util.concurrent.LinkedBlockingQueue;
import java.util.concurrent.ThreadPoolExecutor;
import java.util.concurrent.TimeUnit;

public class ThreadLocalOOMExample {
    static class MyTask {
        // 10 MB array
        private byte[] bytes = new byte[10 * 1024 * 1024];
    }

    private static ThreadLocal<MyTask> taskThreadLocal = new ThreadLocal<>();

    public static void main(String[] args) throws InterruptedException {
        ThreadPoolExecutor threadPoolExecutor =
                new ThreadPoolExecutor(5, 5, 60,
                        TimeUnit.SECONDS, new LinkedBlockingQueue<>(100));
        for (int i = 0; i < 10; i++) {
            executeTask(threadPoolExecutor);
            Thread.sleep(1000);
        }
    }

    private static void executeTask(ThreadPoolExecutor threadPoolExecutor) {
        threadPoolExecutor.execute(new Runnable() {
            @Override
            public void run() {
                System.out.println("创建对象");
                MyTask myTask = new MyTask();
                taskThreadLocal.set(myTask);
                myTask = null; // object no longer used
            }
        });
    }
}

Analyzing the source of ThreadLocal.set() reveals that each thread holds a ThreadLocalMap containing Entry objects (key = ThreadLocal, value = stored object). When a thread pool thread lives for a long time, its map retains the large objects, preventing garbage collection and causing memory leaks.

The fix is straightforward: after the ThreadLocal is no longer needed, call remove() to clear the entry from the thread’s map.

import java.util.concurrent.LinkedBlockingQueue;
import java.util.concurrent.ThreadPoolExecutor;
import java.util.concurrent.TimeUnit;

public class App {
    static class MyTask {
        private byte[] bytes = new byte[10 * 1024 * 1024];
    }

    private static ThreadLocal<MyTask> taskThreadLocal = new ThreadLocal<>();

    public static void main(String[] args) throws InterruptedException {
        ThreadPoolExecutor threadPoolExecutor =
                new ThreadPoolExecutor(5, 5, 60,
                        TimeUnit.SECONDS, new LinkedBlockingQueue<>(100));
        for (int i = 0; i < 10; i++) {
            executeTask(threadPoolExecutor);
            Thread.sleep(1000);
        }
    }

    private static void executeTask(ThreadPoolExecutor threadPoolExecutor) {
        threadPoolExecutor.execute(new Runnable() {
            @Override
            public void run() {
                System.out.println("创建对象");
                try {
                    MyTask myTask = new MyTask();
                    taskThreadLocal.set(myTask);
                    // other business logic
                } finally {
                    taskThreadLocal.remove(); // release memory
                }
            }
        });
    }
}

Running the corrected program shows no OOM, confirming that invoking remove() releases the ThreadLocal reference even when the thread itself remains alive.

In summary, ThreadLocal itself is not the source of memory leaks; improper usage without cleanup is. Understanding its internal implementation helps avoid such pitfalls and is valuable for interviews and real‑world Java development.