How to Keep Spring Boot WebFlux Fast with Blocking Calls

A single slow database query shouldn’t bring your entire Spring Boot WebFlux application to a standstill. When that legacy JDBC call or external API blocks the main event loop, your users start seeing spinners instead of responses. The solution isn’t to abandon reactive programming—it’s to reroute the traffic before it causes a bottleneck.

In this guide, we’ll explore why blocking calls break non-blocking systems and how to move them out of the critical path using Project Reactor’s scheduling tools. You’ll see step-by-step examples in Java 21 that keep your threads free and your application responsive, even when dealing with legacy dependencies.

The Hidden Cost of Blocking Calls in Reactive Apps

Spring Boot WebFlux thrives on non-blocking I/O—its event loop juggles thousands of connections without breaking a sweat. But when a blocking operation sneaks into the pipeline—whether it’s a JDBC query, file I/O, or a third-party API that wasn’t designed for reactive streams—the event loop stalls. It’s like having a single cashier suddenly hand-grinding burgers instead of taking orders.

The consequences are immediate:

• Requests queue up behind the blocked thread
• Response times spike under load
• Thread pools exhaust quickly, leading to crashes
• The entire application loses its scalability edge

To prevent this, we need a way to offload blocking work to specialized workers while keeping the main event loop free.

Offloading Blocking Tasks with Schedulers

Think of Schedulers as dedicated waiting rooms with their own staff. When a blocking task arrives, the event loop hands it off to the waiting room, continues processing other requests, and gets notified only when the task completes. This keeps the main event loop from getting bogged down.

Project Reactor provides several scheduler options, but not all are suitable for blocking calls:

• Schedulers.parallel() – Best for CPU-intensive work, not blocking I/O
• Schedulers.boundedElastic() – Designed specifically for blocking operations
• Schedulers.single() – For sequential work on a single thread
• Schedulers.fromExecutor() – Custom thread pool for specialized needs

For most blocking scenarios in WebFlux, Schedulers.boundedElastic() is the right choice. It dynamically adjusts its thread pool size based on demand, preventing resource exhaustion.

Practical Example: Converting a Legacy JDBC Call

Let’s convert a traditional blocking service into a reactive-friendly version. We’ll use Mono.fromCallable() to wrap the legacy call and shift execution to boundedElastic using .subscribeOn().

Start by adding the required dependency to your pom.xml:

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

Next, create a service that wraps the blocking JDBC call:

import reactor.core.publisher.Mono;
import reactor.core.scheduler.Schedulers;
import org.springframework.stereotype.Service;

@Service
public class CustomerDataService {

    // Legacy blocking method simulating a slow JDBC query
    public String fetchCustomerDetails(long customerId) {
        try {
            // Simulate 2-second delay for database round-trip
            Thread.sleep(2000);
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
        }
        return "Customer " + customerId + " data";
    }

    // Reactive wrapper that moves blocking work off the event loop
    public Mono<String> getCustomerDataReactive(long customerId) {
        return Mono.fromCallable(() -> fetchCustomerDetails(customerId))
                   .subscribeOn(Schedulers.boundedElastic());
    }
}

Now expose the endpoint in a controller:

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RestController;
import reactor.core.publisher.Mono;

@RestController
public class CustomerController {

    private final CustomerDataService customerService;

    public CustomerController(CustomerDataService customerService) {
        this.customerService = customerService;
    }

    @GetMapping("/customers/{id}")
    public Mono<String> getCustomer(@PathVariable long id) {
        return customerService.getCustomerDataReactive(id)
                              .map(data -> "Processed: " + data);
    }
}

Start your Spring Boot application and test the endpoint. Even though the simulated database call takes 2 seconds, incoming requests won’t queue up because the blocking work happens on boundedElastic, not the event loop.

Best Practices for Reactive Blocking Calls

To maintain a clean, high-performance reactive application, follow these guidelines:

• Always use `boundedElastic` for blocking I/O – Never route blocking calls to parallel or single schedulers.

• Keep blocking wrappers close to the source – Isolate legacy logic in service layers rather than letting it leak into controllers or utility classes.

• Avoid `.block()` at all costs – Calling .block() inside a reactive chain defeats the purpose of non-blocking I/O and can crash your application under load.

• Monitor thread pool usage – Tools like Micrometer can track boundedElastic pool size. If threads are consistently maxed out, investigate potential bottlenecks in your legacy systems.

• Consider virtual threads for CPU-bound tasks – Java 21’s virtual threads offer lightweight concurrency for CPU-intensive work, reducing thread overhead.

Looking Ahead: Building Truly Resilient Systems

Mastering the balance between reactive programming and legacy integration unlocks new levels of scalability and responsiveness. By offloading blocking operations to the right schedulers, you ensure your Spring Boot WebFlux applications remain fast and reliable, even when dealing with older dependencies.

The next step is to audit your existing codebase for hidden blocking calls. Start with database access layers, file operations, and third-party integrations. Refactor one service at a time, measure performance improvements, and gradually transform your application into a fully optimized reactive system.

As you refine these patterns, you’ll not only improve throughput but also future-proof your architecture against the inevitable evolution of technology stacks.