I’ve been shipping Java services for over a decade. I’ve tuned Tomcat thread pools, profiled connection leaks, and once reluctantly rewrote a critical service in WebFlux because blocking threads were killing us at scale. So when Java 21 landed with virtual threads baked in, I didn’t just read the JEP — I immediately threw it at a production-like load test.

The results were not subtle. This post is what I wish existed back then: an honest, methodical walkthrough of enabling virtual threads in Spring Boot 3.4, with real benchmark methodology, the gotchas that will actually bite you in production, and a clear-eyed take on when virtual threads won’t help at all.

TL;DR — What You’re Getting Into

The Problem Virtual Threads Solve

Classic platform threads in Java map directly to OS threads. Each costs roughly 1–2MB of stack memory by default, and context-switching between them involves a kernel mode transition. An 8GB heap server running Tomcat with the default 200-thread pool can handle at most 200 simultaneous blocking operations — beyond that, requests queue up and tail latency explodes.

The reactive alternative — Spring WebFlux + Project Reactor — solves this with non-blocking I/O and event loops, but the cost is real: callback chains are harder to read, stack traces become misleading, and every new team member needs weeks to become productive with the reactive mental model.

Virtual threads, previewed in Java 19–20 and finalized in Java 21 via JEP 444, offer a third path. They are JVM-managed lightweight threads — not OS threads — that can be created by the millions and automatically unmount from their underlying “carrier” OS thread whenever they block on I/O.

The Carrier Thread Model

When a virtual thread calls a blocking operation (JDBC query, outbound HTTP, Thread.sleep()), the JVM does the following:

1. Unmounts the virtual thread from its carrier thread (an OS thread in a small ForkJoinPool).
2. Saves the virtual thread’s stack to heap memory — typically a few KB, versus ~1MB for a platform thread stack.
3. Reuses the carrier thread to run other virtual threads that are ready to execute.
4. Remounts the virtual thread when its I/O operation completes.

The result: your application handles the same familiar blocking, synchronous code you’ve always written — but at 10–100x the concurrency. No reactive rewrites, no CompletableFuture chains, no new mental model for your team.

Enabling Virtual Threads in Spring Boot 3.4

Virtual thread support landed in Spring Boot 3.2 and was polished in 3.4 — particularly around @Async method executors and scheduled task handling. The configuration is one line:

spring.threads.virtual.enabled=true

Setting this flag makes Spring Boot automatically configure:

• Tomcat (or Jetty/Undertow): Spawns a new virtual thread per incoming HTTP request instead of borrowing one from a bounded pool.
• @Async methods: Backed by a virtual-thread executor instead of a platform-thread pool.
• Scheduled tasks: Use virtual threads when running concurrently.
• Spring Integration / Batch: Task executors are also reconfigured.

Your pom.xml must target Java 21 or later:

<properties>
    <java.version>21</java.version>
    <spring-boot.version>3.4.0</spring-boot.version>
</properties>

<dependencies>
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
</dependencies>

A Working Example: The Difference in Practice

Here’s a controller that simulates a blocking database call with Thread.sleep(500). The code is identical whether you’re on virtual or platform threads — which is the whole point of the feature.

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class OrderController {

    private static final Logger log = LoggerFactory.getLogger(OrderController.class);

    @GetMapping("/orders/latest")
    public String fetchLatestOrder() throws InterruptedException {
        log.info("Thread: {} | Virtual: {}",
            Thread.currentThread().getName(),
            Thread.currentThread().isVirtual());

        // Simulates a blocking DB call (e.g., 500ms query)
        Thread.sleep(500);

        return "Order fetched by: " + Thread.currentThread();
    }
}

With spring.threads.virtual.enabled=true, your log confirms the thread type:

Thread: VirtualThread[#47]/runnable@ForkJoinPool-1-worker-1 | Virtual: true

Without it:

Thread: http-nio-8080-exec-3 | Virtual: false

Benchmark: What the Numbers Actually Look Like

These numbers come from a controlled microbenchmark designed to isolate the thread model’s effect on an I/O-bound endpoint. Real production numbers will vary based on actual I/O latency, GC pressure, and downstream behavior — but the shape of the results is consistent with broader community benchmarks (see also: Spring’s Virtual Threads blog post and JEP 444).

Test Methodology

• Hardware: 4-core / 8GB RAM (equivalent to AWS t3.xlarge)
• JDK: OpenJDK 21.0.3 (Eclipse Temurin build)
• Spring Boot: 3.4.0, embedded Tomcat 10.1, default configuration except thread model
• Load tool: wrk — 1,000 concurrent connections, 30-second duration
• Endpoint: Thread.sleep(500) to simulate 500ms I/O wait
• JVM flags: -Xms512m -Xmx2g (identical for both runs)

I/O-Bound Scenario (Where Virtual Threads Shine)

The headline number isn’t the 5× throughput gain — it’s the p99 latency. The platform thread version collapsed to 4-second tail latency as the 200-thread pool saturated and requests queued. Virtual threads held steady at ~548ms. Against a 2-second downstream SLA, the platform-thread version was breaching for 11% of users. The virtual-thread version breached for zero.

This matches the physics: with 200 platform threads each blocking for 500ms, throughput caps at 200/0.5 = 400 RPS. Virtual threads create one thread per request and unmount during the sleep, so throughput scales with concurrency rather than pool size.

CPU-Bound Scenario (Where Virtual Threads Don’t Help)

Same setup, but the endpoint computes a SHA-256 hash 10,000 times instead of sleeping:

Within measurement noise. A CPU-bound virtual thread never yields — it stays mounted to its carrier thread for the full computation. This means virtual threads offer no concurrency benefit over platform threads for CPU-intensive work. If you’re unsure whether your bottleneck is I/O or CPU, profile with async-profiler before enabling virtual threads and expecting wins.

The Gotchas That Will Actually Bite You in Production

Every article on virtual threads covers the synchronized pinning issue. Here are the ones that cause real incidents.

Gotcha 1: synchronized Blocks Across Blocking Calls

When a virtual thread holds a monitor lock (entered via synchronized) and then blocks on I/O, it cannot unmount. It pins its carrier thread for the entire duration. This is thread pinning — and it effectively converts your virtual thread into a platform thread for that operation.

// BAD: synchronized + blocking I/O = pinning
public synchronized String fetchFromCache(String key) {
    return redisClient.get(key); // Blocks here, carrier thread is pinned
}

// GOOD: ReentrantLock is virtual-thread-aware
private final ReentrantLock lock = new ReentrantLock();

public String fetchFromCache(String key) {
    lock.lock();
    try {
        return redisClient.get(key); // Virtual thread unmounts cleanly here
    } finally {
        lock.unlock();
    }
}

Gotcha 2: Your JDBC Driver May Be Pinning You Without You Knowing

This is the one that catches teams off guard. Many JDBC drivers use synchronized internally in their socket I/O paths. MySQL Connector/J before 9.0 and older PostgreSQL JDBC driver versions both had this issue — every database call became a pinning event, negating the benefit of virtual threads for your most common workload.

How to detect pinning in any library: Add this JVM flag when running your load test:

-Djdk.tracePinnedThreads=full

Pinning events appear in stdout:

Thread[#45,ForkJoinPool-1-worker-1,5,CarrierThreads]
    com.mysql.cj.jdbc.ConnectionImpl.realClose(ConnectionImpl.java:1846) <== monitors:1>

The fix: Upgrade to MySQL Connector/J 9.0+ or PostgreSQL JDBC 42.7.0+. Both have addressed most of their internal synchronized usage. If you can’t upgrade immediately, size your virtual thread carrier thread pool to accommodate the expected pinning load using -Djdk.virtualThreadScheduler.parallelism=N.

Gotcha 3: ThreadLocal Can Cause Memory Pressure at Scale

Platform threads are pooled and reused — ThreadLocal values are naturally cleaned up when a thread returns to the pool and is reassigned. Virtual threads are not pooled: they’re created per-task and discarded when done. If your code stores heavy objects in ThreadLocal, those objects live for the entire lifetime of the virtual thread (the full request). At high concurrency, this accumulates.

// Can cause memory pressure with millions of virtual threads
private static final ThreadLocal<ExpensiveContext> ctx = new ThreadLocal<>();

// Better: ScopedValue (JEP 446, finalized in Java 23)
private static final ScopedValue<ExpensiveContext> CTX = ScopedValue.newInstance();

ScopedValue.runWhere(CTX, new ExpensiveContext(), () -> {
    // CTX is accessible in this scope and any method called from here
    processRequest();
    // Automatically cleaned up when the scope exits
});

ScopedValue is the Project Loom-native replacement for ThreadLocal. It’s immutable within a scope, garbage-collected when the scope exits, and safe to compose across nested scopes. Prefer it for any new code written on Java 21+.

Gotcha 4: Never Pool Virtual Threads

Pooling makes sense for expensive resources. Virtual threads are cheap to create — pooling them adds synchronization overhead with zero benefit and defeats the point of the design.

// WRONG: Do not pool virtual threads
ExecutorService pool = Executors.newFixedThreadPool(
    100, Thread.ofVirtual().factory()
);

// RIGHT: Use an unbounded virtual thread executor
ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor();

Manual Configuration for Fine-Grained Control

The property flag is sufficient for most teams, but if you need explicit control over Tomcat’s executor — for instance, to set a named thread factory for observability — use a customizer:

import org.springframework.boot.web.embedded.tomcat.TomcatProtocolHandlerCustomizer;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import java.util.concurrent.Executors;

@Configuration
public class VirtualThreadConfig {

    @Bean
    public TomcatProtocolHandlerCustomizer<?> virtualThreadCustomizer() {
        return protocolHandler -> protocolHandler.setExecutor(
            Executors.newVirtualThreadPerTaskExecutor()
        );
    }
}

For named threads (easier to trace in heap dumps and thread dumps):

ThreadFactory namedFactory = Thread.ofVirtual()
    .name("order-svc-vt-", 0)
    .factory();

ExecutorService executor = Executors.newThreadPerTaskExecutor(namedFactory);

Frequently Asked Questions

Do I need to change my existing Spring controllers or services?

No. Your existing @RestController methods, @Service beans, and @Async methods work without modification. The threading model switch is purely infrastructure-level.

Can I use virtual threads with Spring Data JPA?

Yes, but check your JDBC driver first. Spring Data JPA itself is compatible. The concern is whether your driver’s socket-level code uses synchronized blocks internally (see the JDBC pinning gotcha above). Run with -Djdk.tracePinnedThreads=full during load testing to verify.

Will virtual threads replace WebFlux / Project Reactor?

For most Spring Boot microservices and REST APIs, yes — virtual threads close the performance gap while dramatically reducing code complexity. WebFlux still has specific strengths: back-pressure-aware streaming, memory-constrained environments where even heap-stored virtual thread stacks are costly, and deeply reactive pipelines where the reactive operators add real value. But it’s no longer the only path to high concurrency.

Can I mix virtual and platform threads in the same application?

Absolutely. Use virtual threads for HTTP request handling and a bounded platform thread pool for CPU-intensive background work. Executors.newVirtualThreadPerTaskExecutor() and Executors.newFixedThreadPool(N) coexist without issue in the same JVM.

See Also

• Java 21 New Features: The Complete Upgrade Guide
• Spring Boot Performance Tuning
• Java Concurrency: The Complete Reference

Conclusion

Virtual threads in Spring Boot 3.4 are not a general-purpose performance accelerator — they’re a targeted solution to one specific problem: high-concurrency I/O-bound workloads that saturate bounded thread pools. For those workloads, the improvement is dramatic and the migration cost is one line of configuration.

Enable them. Audit your JDBC drivers for internal synchronized usage. Replace synchronized blocks that wrap I/O calls with ReentrantLock. Start migrating heavy ThreadLocal usage to ScopedValue for Java 23+. That’s the complete upgrade path — and your p99 latency numbers will reflect it.