zero gravitySOLUTIONS
← All insightsJAVA & PERFORMANCE / DIAGNOSTIC WALKTHROUGH

Finding blocking calls in WebFlux

QUICK ANSWER

Test suspect WebFlux paths with a known blocking fixture, then combine blocking-call detection with traces and thread evidence. Move unavoidable synchronous work to a bounded execution boundary and verify that queueing, timeouts, and dependency limits remain controlled.

Inside this article 4 sections

A method returning Mono can still perform blocking work. A synchronous client call, filesystem read, or sleep inside the request path can occupy a thread that other requests need. The return type tells you about the result protocol; it does not prove that every instruction leading to that result is non-blocking.

Investigation should establish where execution happens and what holds it there. Start with a repeatable symptom, then create a fixture that proves your diagnostic setup can detect a known problem. Otherwise, a quiet detector may simply mean that the relevant code never ran in the test.

Build two paths that share the same server

In a test-only application, expose a lightweight health-like endpoint and a second endpoint whose dependency adapter deliberately performs a synchronous wait. This is a diagnostic fixture, not production behavior. Drive both paths concurrently and collect request timings separately. The useful question is whether the introduced wait interferes with requests that do not need that dependency.

Use the same server runtime and request-processing configuration as the application under investigation. Record JDK, Spring, Reactor, and diagnostic-tool versions. A unit test that calls an adapter directly from an ordinary test thread does not recreate execution on a non-blocking request thread. Exercise the actual chain through an integration test before drawing conclusions.

CONTROLLED DIAGNOSTIC / NO BENCHMARK CLAIM
Control request
Return a small response without calling the suspect dependency.
Probe request
Execute a known synchronous wait at the same boundary as the suspect adapter.
Evidence
Compare route timings, execution threads, detector reports, and dependency spans.
Isolation check
Repeat after moving only the blocking boundary to bounded execution.
The control route reveals collateral interference. An improved probe response alone cannot establish that the shared execution path is healthy.

Use blocking detection as a targeted signal

BlockHound can report instrumented blocking calls made from threads identified as non-blocking. Install it early in the supported test setup and verify the known fixture fails as expected. Follow the compatibility requirements for the selected JDK and tool versions. Do not assume that a detector embedded in one test process covers another server process.

A report gives a starting location, not a complete performance diagnosis. Inspect the stack to find the application boundary responsible for calling the library. A JSON serializer or logger may invoke an unexpected synchronous operation below an innocent-looking method. Fixing the ownership boundary is usually more durable than adding a broad allowlist around the library package.

Absence of a report also has limits. Busy CPU computation can monopolize execution without using a recognized blocking primitive. An uninstrumented native call may escape detection. Pair detector results with a profiler or thread recording, event-loop responsiveness, and traces that show elapsed time around the suspect adapter.

Check subscription timing before changing schedulers

A common mistake is executing the slow method first and then wrapping its result in a publisher. By that point the wait has already occurred. Defer the synchronous call until subscription and assign its execution boundary at the source. The precise implementation should be tested against the installed Reactor version, but the design requirement is stable: scheduling cannot move work that has already happened.

Another mistake is placing a scheduler change after the expensive source and assuming the earlier work will follow it. Reactor operators differ in which part of the sequence they affect. Trace the actual thread at the source and at downstream transformations. Avoid scattering scheduler changes throughout the chain; they make execution ownership difficult to understand and can hide another queue.

Where the dependency has a suitable non-blocking client, evaluate replacing the adapter. Where it must remain synchronous, use a bounded execution facility such as an appropriately configured bounded-elastic scheduler. This protects the non-blocking path, but it creates finite worker and waiting capacity that needs monitoring and an overload policy.

This Java adapter fragment assumes Reactor imports, a synchronous legacyDirectory, and an application-defined Account type. The important boundary is the lambda: constructing the publisher does not call the directory.

Mono<Account> loadAccount(String accountId) {
    return Mono.fromCallable(() -> legacyDirectory.find(accountId))
        .subscribeOn(Schedulers.boundedElastic())
        .switchIfEmpty(Mono.error(
            new IllegalStateException("Account was not found")
        ));
}

A null result becomes an empty Mono, so the adapter gives absence an explicit outcome. Test that the call occurs on the intended scheduler and that saturation does not block the control endpoint. This isolates a synchronous dependency; it does not make that dependency non-blocking or add a per-provider admission limit. Set client timeouts and review the executor queue as part of the integration.

Prove the fix under saturation

Repeat the fixture after isolation and compare both routes. The control route should no longer inherit the same execution blockage, while the probe route may still wait for its dependency. That distinction matters: moving a slow call does not make the remote service faster. Track the additional executor queue rather than interpreting lower event-loop delay as unlimited capacity.

Set limits using downstream capacity. A blocking database adapter backed by a small connection pool should not accumulate an unbounded number of waiting tasks. Give calls deadlines and decide what happens when admission is exhausted. Cancellation is not proof that a synchronous operation stopped; verify the driver's behavior and keep business outcomes safe if it completes after the request ends.

Turn the confirmed regression into a focused integration check and keep the deliberate blocking fixture separate from production code. The broader reactive Java resource guide helps choose the execution model, while an architecture review before a rewrite keeps the remedy proportional. This diagnostic work belongs in performance and architecture design whenever one dependency can disrupt unrelated traffic.

FROM INSIGHT TO ACTIONSoftware architecture consulting

Make reactive performance evidence actionable.

We can reproduce a blocking path, isolate its dependency, and validate the resulting latency and capacity limits.

Explore architecture consultingDiscuss your architecture

Start with your goals.
We’ll work through the next step together.