What are Spring Boot virtual threads and how do they work?

A virtual thread is a java.lang.Thread that the JVM schedules, not the operating system. Project Loom keeps the familiar thread API but separates the Java thread from the OS thread underneath it. The JVM runs virtual threads on a small pool of carrier threads, which are ordinary platform threads sized roughly to the number of CPU cores.

When a virtual thread runs, it is mounted on a carrier. When it reaches a blocking operation the JDK knows how to handle, such as a socket read, a JDBC call over a network socket, or Thread.sleep, the JVM saves its stack to the heap and unmounts it. The carrier is then free to run another virtual thread. When the IO completes, the virtual thread is rescheduled, possibly on a different carrier, and continues where it stopped.

This is the core benefit. Sequential blocking code, the style most Spring MVC applications already use, no longer holds an OS thread while it waits. A request that spends most of its time waiting on downstream calls costs a heap-allocated stack instead of a megabyte-scale native stack and a kernel thread.

Pinning breaks this model. A pinned virtual thread cannot unmount while it blocks, so it holds its carrier for the whole wait. Native frames always cause pinning. Depending on the JDK version, blocking inside a synchronized block can also cause it. Because there are only a few carriers, a handful of pinned threads can stall every other virtual thread in the application, which is why later sections focus on detecting pinning.

  VIRTUAL THREADS (java.lang.Thread, scheduled by the JVM, can be many)
  +----------+ +----------+ +----------+ +----------+ +----------+
  |   VT-1   | |   VT-2   | |   VT-5   | |   VT-4   | |   VT-3   |
  | running  | | running  | |  PINNED  | | blocked  | |  ready   |
  |          | |          | | blocks in| | on socket| | (queued) |
  |          | |          | | native/  | |   read   | |          |
  |          | |          | | sync code| |          | |          |
  +----+-----+ +----+-----+ +----+-----+ +----+-----+ +----------+
       |            |            |            |
    mounted      mounted  cannot unmount   unmount     waits for a
       |            |            |            |        free carrier
       v            v            v            v
  +----------+ +----------+ +----------+ +-------------------+
  | Carrier 1| | Carrier 2| | Carrier 3| | HEAP              |
  | platform | | platform | | held for | | VT-4 stack saved; |
  | thread   | | thread   | | the whole| | on IO completion  |
  |          | |          | | wait     | | rescheduled on    |
  |          | |          | |          | | any free carrier  |
  +----+-----+ +----+-----+ +----+-----+ +-------------------+
       |            |            |
       v            v            v
  +--------------------------------------+
  | OS threads / kernel                  |
  | carrier pool ~ number of CPU cores   |
  +--------------------------------------+

  Pinned VT-5 occupies Carrier 3, so VT-3 and others have fewer carriers.

Virtual threads mount on a small pool of carrier platform threads and unmount to the heap when they block on supported IO, while a pinned virtual thread keeps its carrier occupied for the entire wait.

How do you enable virtual threads in Spring Boot?

Enabling virtual threads takes one property: set spring.threads.virtual.enabled=true and run on a JDK that supports virtual threads. Spring Boot then switches the executors it auto-configures. The embedded servlet container handles each request on a new virtual thread instead of a pooled platform thread. The auto-configured task executor behind @Async, and the auto-configured scheduler, also create virtual threads. Your controllers, JDBC calls and HTTP clients stay as they are. Compare that with a reactive migration, where every layer from controller to driver has to be rewritten into non-blocking types and retested. Here the change is one line of config plus a test cycle.

The property only reaches executors that Spring Boot builds itself. Some thread pools stay on platform threads:

  • Pools created in code with Executors.newFixedThreadPool, new ThreadPoolExecutor(...), or a hand-declared ThreadPoolTaskExecutor bean. A custom executor bean also makes Boot's auto-configured one back off.
  • CompletableFuture.supplyAsync called without an executor, which runs on the common ForkJoinPool.
  • Pools that client libraries create internally.

To audit, search the codebase for those constructors and for @Bean methods that return executors. At runtime, log Thread.currentThread().isVirtual() at entry points, or take a thread dump under load.

Mixed codebases are confusing because nothing fails. A request can start on a virtual thread and then hand work to a fixed pool of 20 platform threads. From that point, concurrency on that path is capped at 20. Throughput improves on some endpoints and stays flat on others. Thread dumps show both kinds of thread, and the cause is often not obvious until you trace each handoff.

# 1. Enable virtual threads for the executors Spring Boot auto-configures.
#    Requires a JDK with virtual threads (21 or later).
echo 'spring.threads.virtual.enabled=true' >> src/main/resources/application.properties

# 2. Audit for pools the property does NOT convert.
#    Direct JDK pools and hand-built Spring executors stay on platform threads.
grep -rnE 'Executors\.new(Fixed|Cached|Scheduled|SingleThread|WorkStealing)|new ThreadPoolExecutor|new ScheduledThreadPoolExecutor|new (ThreadPoolTaskExecutor|ThreadPoolTaskScheduler)' \
  --include='*.java' --include='*.kt' src/

# 3. Async calls without an explicit executor run on the common ForkJoinPool.
#    Review each hit: a one-argument call means no executor was passed.
grep -rnE '(supplyAsync|runAsync)\(' --include='*.java' --include='*.kt' src/

# 4. Executor beans you declare yourself also make Boot's auto-configured
#    executor back off. List @Bean methods that return executors.
grep -rnE -A2 '@Bean' --include='*.java' src/ \
  | grep -E 'Executor|TaskScheduler'

# 5. Under load, confirm what actually runs. Virtual threads only appear
#    in the newer thread dump format, not in the default jstack-style dump.
PID=$(pgrep -f 'my-service.jar')   # placeholder jar name
jcmd "$PID" Thread.dump_to_file -format=json /tmp/threads.json

# Platform pool workers show up by name (e.g. pool-3-thread-7) in the classic dump:
jcmd "$PID" Thread.print | grep -E '^"(pool-[0-9]+-thread|ForkJoinPool)' | sort | uniq -c | head

Enabling virtual threads with one property, then grepping for executors it leaves on platform threads and checking thread dumps under load to find mixed virtual/platform paths.

When do virtual threads actually improve throughput?

The cleanest way to reason about the gain is Little's law: concurrency = arrival rate × latency. Rearranged, the maximum throughput a server can sustain is the number of requests it can hold in flight divided by how long each one takes.

Illustrative estimate, with assumed inputs: a platform-thread pool of 200 threads, where each request spends about 100 ms waiting on IO. Each thread completes roughly 10 requests per second, so the pool tops out near 200 / 0.1 s ≈ 2,000 req/s. Beyond that, requests queue for a thread. Latency climbs while CPU stays mostly idle, because the threads are parked rather than working.

Virtual threads remove that particular ceiling. A blocked virtual thread unmounts from its carrier, so in-flight requests no longer map one-to-one to OS threads, and holding 5,000 concurrent waits becomes cheap. That is the only thing they change. Each request takes just as long, and every downstream call still happens. Little's law then applies to the next resource in the chain: the connection pool, a partner API's rate limit, a cache cluster's connection cap, or CPU once the waiting is gone. Throughput rises until whichever of those saturates first. After that point it flattens again, and latency usually gets worse.

The services that benefit look similar. Most of each request's wall-clock time goes to blocking IO, such as HTTP calls, JDBC, or message brokers. The resources behind those calls must have spare capacity to absorb more concurrent work. If either condition is missing, the thread pool was not your constraint.

Why does the database connection pool become the new bottleneck?

Consider a service whose Tomcat pool had 200 platform threads and whose JDBC pool holds 20 connections. Under load, at most 200 requests were in flight, and the excess waited in Tomcat's accept queue. With virtual threads, every incoming request gets its own thread, so 5,000 concurrent requests can all reach the point where they ask for a connection. Only 20 can proceed. The rest park inside the pool's acquisition call. Throughput stays capped at what 20 connections can serve, while latency climbs because each request now waits in a deeper queue. When waits exceed the pool's acquisition timeout, requests fail.

Implicit backpressure is gone

The bounded thread pool was a crude admission-control mechanism. It limited concurrency at the edge, before requests consumed memory, held locks, or touched downstreams. Virtual threads remove that limit, so you have to restore it deliberately:

  • Semaphores or bulkheads around each scarce resource, sized to its real capacity.
  • Bounded queues that reject work instead of letting waiters accumulate without limit.
  • Rate limits on calls to shared services.
  • Short acquisition and request timeouts, so callers fail fast instead of piling up.

The tuning work does not go away. It moves from thread pool size to these limits.

The larger risk is systemic. If one instance can now push far more concurrent queries or HTTP calls, a database or service shared by many instances can be overloaded. The result is a fleet that is faster per instance and less stable as a whole.

import java.sql.Connection;
import java.sql.SQLException;
import java.util.concurrent.Semaphore;
import java.util.concurrent.TimeUnit;
import javax.sql.DataSource;
import org.springframework.stereotype.Component;

@Component
public class DbBulkhead {
    // Sized to the JDBC pool (e.g. 20 connections), not to request concurrency.
    private static final int PERMITS = 20;
    // Short bounded wait: excess callers fail fast instead of parking indefinitely.
    private static final long MAX_WAIT_MS = 200;

    private final Semaphore permits = new Semaphore(PERMITS, true);
    private final DataSource dataSource;

    public DbBulkhead(DataSource dataSource) { this.dataSource = dataSource; }

    public <T> T withConnection(SqlWork<T> work) throws SQLException, InterruptedException {
        // Explicit admission control: replaces the limit the old 200-thread pool gave us.
        if (!permits.tryAcquire(MAX_WAIT_MS, TimeUnit.MILLISECONDS)) {
            // Map this to HTTP 503 so clients and load balancers can back off.
            throw new BulkheadFullException("database bulkhead full");
        }
        try (Connection conn = dataSource.getConnection()) {
            return work.apply(conn);
        } finally {
            permits.release(); // always return the permit, even on failure
        }
    }

    @FunctionalInterface
    public interface SqlWork<T> { T apply(Connection conn) throws SQLException; }

    public static class BulkheadFullException extends RuntimeException {
        public BulkheadFullException(String msg) { super(msg); }
    }
}

A semaphore-based bulkhead sized to the JDBC pool, with a short acquisition timeout, restores the backpressure that a bounded Tomcat thread pool used to provide, so excess virtual threads are rejected quickly rather than queuing inside the connection pool.

When should you avoid virtual threads in Spring Boot?

Virtual threads make waiting cheap. They do not make computing cheaper, so a handler that spends most of its time on the CPU gains little.

CPU-bound handlers

Consider services dominated by JSON or Protobuf serialization of large payloads, TLS-heavy or cryptographic work, image processing, or in-memory aggregation. Virtual threads run on a carrier pool sized to the available cores, so the number of handlers doing useful work at once is still capped by core count. Switching such a service adds a scheduling layer between your code and the OS threads without adding capacity. It can also hide the real fix: if p99 latency is mostly compute, you need more cores, a better algorithm, or less work per request. A thread model change does not address any of these.

Per-thread caches and pooled objects

Code that caches expensive objects in a ThreadLocal, such as formatters, buffers, or digest instances, assumes a small, long-lived pool of threads that reuses them. With one virtual thread per request, each thread is new, so the cache is filled once and then discarded. The cost is never amortized, and with unbounded thread counts, memory and allocation pressure rise. Replace these caches with immutable shared instances or an explicit bounded object pool.

Context does not get easier either. MDC, the security context and tracing context are still thread-bound. Any hand-off to another executor still needs the same propagation discipline as before.

Workload Expected effect
Blocking IO, high concurrency Likely gain
Serialization/crypto/compute-heavy Little or none
Latency mostly compute Little or none
Heavy ThreadLocal caching Can regress

How do you detect thread pinning and carrier starvation?

A virtual thread that blocks normally unmounts from its carrier, freeing that platform thread for other work. When it is pinned, it cannot unmount. Pinning happens during native or foreign function calls and, on older JDKs, inside synchronized blocks or methods. Blocking while pinned holds the carrier for the full duration of the IO. The scheduler has only about as many carriers as CPU cores, so a handful of pinned threads stuck on slow sockets can take all of them. At that point runnable virtual threads queue with no carrier to run on. Under normal traffic this rarely happens. At peak load, when slow downstream calls overlap, it appears as deadlock-like stalls or sudden latency spikes with low CPU usage.

Finding it

  • JDK Flight Recorder emits a virtual-thread pinning event (jdk.VirtualThreadPinned) when a thread blocks while pinned beyond a threshold. The event includes a stack trace, which points you to the frame holding the monitor or making the native call.
  • Thread dumps that include virtual threads, such as jcmd <pid> Thread.dump_to_file, show where virtual threads are parked. Expect very large files: tens of thousands of threads is normal, so search and group stacks with tools instead of reading the file.
  • Library audit: look for drivers, connection pools, and caches that hold a monitor across socket reads or writes.

Pinning behavior has changed between JDK releases. Check the release notes for the JDK you run instead of relying on older guidance.

Also adjust your monitoring. Thread-pool saturation dashboards stop meaning much when each request gets its own thread. Watch carrier utilization, pinning event counts, and connection-pool wait times instead.

#!/usr/bin/env bash
# Capture pinning evidence from a running Spring Boot service during peak load.
set -euo pipefail

PID=$(pgrep -f 'orders-service.jar')   # placeholder app name
OUT=/tmp/loom-diag
mkdir -p "$OUT"

# 1. Record 2 minutes of JFR. The default settings enable
#    jdk.VirtualThreadPinned, which fires when a virtual thread
#    blocks while pinned for longer than a threshold.
jcmd "$PID" JFR.start name=pinning settings=default \
  duration=120s filename="$OUT/pinning.jfr"
sleep 125

# 2. How many pinning events occurred in the window?
jfr summary "$OUT/pinning.jfr" | grep VirtualThreadPinned || true

# 3. Print the events with stack traces. Look for the frame that holds
#    a monitor or makes a native call, such as a driver or pool doing socket IO.
jfr print --events jdk.VirtualThreadPinned "$OUT/pinning.jfr" | head -n 80

# 4. Take a thread dump that includes virtual threads. JSON output is easier to process
#    with tools, which matters because the file can hold tens of thousands of threads.
jcmd "$PID" Thread.dump_to_file -format=json "$OUT/threads.json"

# 5. Don't read the dump by hand. Group threads by their top stack frame
#    to find where most of them are parked.
jq -r '.threadDump.threadContainers[].threads[] | .stack[0] // "<no frames>"' \
  "$OUT/threads.json" | sort | uniq -c | sort -rn | head -n 20

A shell session that records JFR virtual-thread pinning events, prints their stack traces, and groups a JSON thread dump by top frame to show where virtual threads pile up (verify the dump's JSON field names against your JDK).

What are the alternatives to virtual threads, and how should you roll them out?

Virtual threads are not the only way to handle high concurrency. Two other approaches remain reasonable, and each trades something different.

Approach Throughput ceiling (IO-bound) Code style Debugging Backpressure Development cost
Tuned platform thread pool Capped by pool size and per-thread memory Imperative, blocking Ordinary stack traces Implicit via queue limits Low, but needs ongoing tuning
Virtual threads Capped by downstream resources (pools, rate limits) Imperative, blocking Ordinary stack traces, very large thread dumps None built in; add semaphores or bulkheads Low for most blocking code
Reactive (non-blocking) Capped by downstream resources Operator chains, async Fragmented stack traces, harder profiling Built into the stream protocol High: different libraries and skills

Virtual threads and reactive stacks hit the same ceiling, which is your downstream capacity. A team with a mature reactive codebase therefore gains little throughput by switching. If it migrates, the case rests on simpler code, easier onboarding and readable stack traces. Weigh those against the cost of the rewrite and of losing built-in backpressure.

A rollout method

Choose one realistic IO-heavy endpoint. Load-test it with spring.threads.virtual.enabled set to true and then to false, using the same traffic shape and dataset for both runs. Compare five measures:

  • throughput
  • p99 latency
  • connection-pool wait time
  • downstream error rates
  • heap usage

Rising pool wait time or downstream errors means you have moved the bottleneck rather than removed it. Resolve that before you enable the property fleet-wide.

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to Spring Boot virtual threads, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.