Virtual Thread Pinning in Spring Boot 3.2+

Overview

Virtual threads (Project Loom) are designed to be lightweight and massively scalable, supporting millions of concurrent tasks on a handful of OS threads. However, 'pinning' occurs when a virtual thread becomes stuck to its carrier (platform) thread — preventing the JVM scheduler from mounting other virtual threads onto it. This commonly happens inside synchronized blocks that perform blocking I/O, or when invoking native methods. The result is silent performance degradation: no exception thrown, just thread exhaustion.

1. 01

   Replace every synchronized block and method with java.util.concurrent.locks.ReentrantLock — virtual threads can yield while waiting to acquire it.

2. 02

   Remove long-lived ThreadLocal usage from async/virtual thread paths; replace with ScopedValue (Preview in Java 21, stable in Java 23).

3. 03

   Upgrade JDBC drivers to Loom-aware versions: PostgreSQL 42.6+, MySQL Connector/J 8.3+, Oracle 23.3+.

4. 04

   Add -Djdk.tracePinnedThreads=full in staging environments to identify all pinning sites before they hit production.

5. 05

   Set spring.threads.virtual.enabled=true in Spring Boot 3.2+ and monitor carrier thread saturation with JFR or Micrometer.

// ❌ PINNING TRAP — synchronized blocks pin the carrier thread
class="hi-ann">@Service
public class UserService {
    private final Object lock = new Object();

    public User findUser(Long id) {
        synchronized (lock) {
            // repository.findById() blocks on JDBC I/O
            // The entire carrier thread is now pinned!
            return repository.findById(id).orElseThrow();
        }
    }
}

// ✅ LOOM-SAFE FIX — ReentrantLock allows virtual threads to yield
class="hi-ann">@Service
public class UserService {
    private final ReentrantLock lock = new ReentrantLock();

    public User findUser(Long id) {
        lock.lock();  // Virtual thread parks here, carrier is FREE to run others
        try {
            return repository.findById(id).orElseThrow();
        } finally {
            lock.unlock();
        }
    }
}

// ✅ MODERN PATTERN — ScopedValue instead of ThreadLocal
// application.yml
// spring:
//   threads:
//     virtual:
//       enabled: true  # Enable virtual threads globally in Boot 3.2+

1. 01

   Audit all third-party dependencies with JFR VirtualThreadPinned events before going live — libraries are often the biggest source of hidden pinning.

2. 02

   Treat synchronized as a code smell in virtual-thread-heavy services; enforce a linting rule in your CI pipeline.

3. 03

   Keep carrier pool size as Runtime.getRuntime().availableProcessors() (the default). Increasing it masks pinning bugs rather than fixing them.

What causes Virtual Thread Pinning in Spring Boot 3.2+ in Spring Boot 3?

The JVM 21 runtime cannot unmount a virtual thread from its carrier when the virtual thread enters a monitor (synchronized block or method). If I/O blocking occurs while holding that monitor — such as a database call or REST request — the entire OS carrier thread blocks. With a ForkJoinPool carrier pool of typically CPU_CORES threads, just a handful of pinned virtual threads can starve the entire scheduling pool.

How do I fix Virtual Thread Pinning in Spring Boot 3.2+?

Replace every synchronized block and method with java.util.concurrent.locks.ReentrantLock — virtual threads can yield while waiting to acquire it. Remove long-lived ThreadLocal usage from async/virtual thread paths; replace with ScopedValue (Preview in Java 21, stable in Java 23). Upgrade JDBC drivers to Loom-aware versions: PostgreSQL 42.6+, MySQL Connector/J 8.3+, Oracle 23.3+. Add -Djdk.tracePinnedThreads=full in staging environments to identify all pinning sites before they hit production. Set spring.threads.virtual.enabled=true in Spring Boot 3.2+ and monitor carrier thread saturation with JFR or Micrometer.

Best practice #1 for preventing Java 21 · Project Loom errors?

Audit all third-party dependencies with JFR VirtualThreadPinned events before going live — libraries are often the biggest source of hidden pinning.

Best practice #2 for preventing Java 21 · Project Loom errors?

Treat synchronized as a code smell in virtual-thread-heavy services; enforce a linting rule in your CI pipeline.

Best practice #3 for preventing Java 21 · Project Loom errors?

Keep carrier pool size as Runtime.getRuntime().availableProcessors() (the default). Increasing it masks pinning bugs rather than fixing them.