Pitfalls of Using ThreadLocal for User Context in Java Applications

In many business systems, interceptors such as Spring filters, HandlerInterceptor, or AOP are used to perform login validation and store the logged‑in user’s ID in a ThreadLocal variable.

According to the coding guidelines, this ThreadLocal should only be accessed within the Spring controller layer because the controller thread shares the same underlying thread as the Spring container.

If a thread pool is used and a task submitted to the pool accesses the same ThreadLocal, the stored user information can be lost, causing hidden failures.

Example code demonstrates the problem: the main thread sets a user ID in ThreadLocal, then starts a new thread that attempts to read it, but the output is 0 because the ThreadLocal value is not propagated to the new thread.

package com.renzhikeji.annotation;

import lombok.Data;
import java.util.HashMap;
import java.util.Map;
import java.util.Optional;

/**
 * @author 认知科技技术团队
 * 微信公众号：认知科技技术团队
 */
public class ThreadLocalDemo {
    public static void main(String[] args) throws InterruptedException {
        LoginUserInfos.setUserId(88L);
        System.out.println(LoginUserInfos.getUserId());

        Thread thread = new Thread(new Runnable() {
            @Override
            public void run() {
                System.out.println(LoginUserInfos.getUserId());
            }
        });

        thread.start();
        thread.join();
    }

    @Data
    public static final class LoginUserInfos {
        private static final String USER_ID = "userId";
        private static final ThreadLocal
> THREAD_LOCAL = new ThreadLocal<>() {
            @Override
            protected Map
initialValue() {
                return new HashMap<>();
            }
        };

        public static void setUserId(Long userId) {
            Map
map = THREAD_LOCAL.get();
            map.put(USER_ID, userId);
        }

        public static Long getUserId() {
            Object userId = THREAD_LOCAL.get().get(USER_ID);
            //不设置默认值，还可能利用NPE异常发现问题喔
            return (Long) Optional.ofNullable(userId).orElse(0L);
        }
    }
}

The output on line 21 is always 0, confirming that the user information was not transferred to the worker thread.

In summary, ThreadLocal is widely used in Java projects and frameworks, but it can easily cause memory leaks and loss of information when misused across thread boundaries.

To mitigate these issues, a Maven rule plugin can be employed to detect the usage of ThreadLocal variables and the classes that wrap them, restricting their use to appropriate layers.

Typical thread‑related classes that should be scanned include Thread, ThreadPoolExecutor, ScheduledThreadPoolExecutor, parallel streams, CompletableFuture’s supplyAsync methods, ForkJoinPool, and any executors returned by Executors.