Handling Errors in Spring WebFlux

1. Overview

In this tutorial, we’ll look at various strategies available for handling errors in a Spring WebFlux project while walking through a practical example.

We’ll also point out where it might be advantageous to use one strategy over another and provide a link to the full source code at the end.

2. Setting Up the Example

The Maven setup is the same as our previous article, which provides an introduction to Spring Webflux.

For our example, we’ll use a RESTful endpoint that takes a username as a query parameter and returns “Hello username” as a result.

First, let’s create a router function that routes the /hello request to a method named handleRequest in the passed-in handler:

@Bean
public RouterFunction<ServerResponse> routeRequest(Handler handler) {
    return RouterFunctions.route(RequestPredicates.GET("/hello")
      .and(RequestPredicates.accept(MediaType.TEXT_PLAIN)), 
        handler::handleRequest);
    }

Next, we’ll define the handleRequest() method which calls the sayHello() method and finds a way of including / returning its result in the ServerResponse body:

public Mono<ServerResponse> handleRequest(ServerRequest request) {
    return 
      //...
        sayHello(request)
      //...
}

Finally, the sayHello() method is a simple utility method that concatenates the “Hello” String and the username:

private Mono<String> sayHello(ServerRequest request) {
    //...
    return Mono.just("Hello, " + request.queryParam("name").get());
    //...
}

So long as a username is present as part of our request e.g. if the endpoint is called as “/hello?username=Tonni“, then, this endpoint will always function correctly.

However, if we call the same endpoint without specifying a username e.g. “/hello”, it will throw an exception.

Below, we’ll look at where and how we can reorganize our code to handle this exception in WebFlux.

3. Handling Errors at a Functional Level

There are two key operators built into the Mono and Flux APIs to handle errors at a functional level.

Let’s briefly explore them and their usage.

3.1. Handling Errors with onErrorReturn

We can use onErrorReturn() to return a static default value whenever an error occurs:

public Mono<ServerResponse> handleRequest(ServerRequest request) {
    return sayHello(request)
      .onErrorReturn("Hello Stranger")
      .flatMap(s -> ServerResponse.ok()
      .contentType(MediaType.TEXT_PLAIN)
      .bodyValue(s));
}

Here we’re returning a static “Hello Stranger” whenever the buggy concatenation function sayHello() throws an exception.

3.2. Handling Errors with onErrorResume

There are three ways that we can use onErrorResume to handle errors:

• Compute a dynamic fallback value
• Execute an alternative path with a fallback method
• Catch, wrap, and re-throw an error e.g. as a custom business exception

Let’s see how we can compute a value:

public Mono<ServerResponse> handleRequest(ServerRequest request) {
    return sayHello(request)
      .flatMap(s -> ServerResponse.ok()
      .contentType(MediaType.TEXT_PLAIN)
          .bodyValue(s))
        .onErrorResume(e -> Mono.just("Error " + e.getMessage())
          .flatMap(s -> ServerResponse.ok()
            .contentType(MediaType.TEXT_PLAIN)
            .bodyValue(s)));
}

Here, we’re returning a String consisting of the dynamically obtained error message appended to the string “Error” whenever sayHello() throws an exception.

Next, let’s call a fallback method when an error occurs:

public Mono<ServerResponse> handleRequest(ServerRequest request) {
    return sayHello(request)
      .flatMap(s -> ServerResponse.ok()
      .contentType(MediaType.TEXT_PLAIN)
      .bodyValue(s))
      .onErrorResume(e -> sayHelloFallback()
      .flatMap(s -> ServerResponse.ok()
      .contentType(MediaType.TEXT_PLAIN)
      .bodyValue(s)));
}

Here, we’re calling the alternative method sayHelloFallback() whenever sayHello() throws an exception.

The final option using onErrorResume() is to catch, wrap, and re-throw an error e.g. as a NameRequiredException:

public Mono<ServerResponse> handleRequest(ServerRequest request) {
    return ServerResponse.ok()
      .body(sayHello(request)
      .onErrorResume(e -> Mono.error(new NameRequiredException(
        HttpStatus.BAD_REQUEST, 
        "username is required", e))), String.class);
}

Here, we’re throwing a custom exception with the message: “username is required” whenever sayHello() throws an exception.

4. Handling Errors at a Global Level

So far, all the examples we’ve presented have tackled error handling at a functional level.

We can, however, opt to handle our WebFlux errors at a global level. To do this, we only need to take two steps:

• Customize the Global Error Response Attributes
• Implement the Global Error Handler

The exception that our handler throws will be automatically translated to an HTTP status and a JSON error body. To customize these, we can simply extend the DefaultErrorAttributes class and override its getErrorAttributes() method:

public class GlobalErrorAttributes extends DefaultErrorAttributes{
    
    @Override
    public Map<String, Object> getErrorAttributes(ServerRequest request, 
      ErrorAttributeOptions options) {
        Map<String, Object> map = super.getErrorAttributes(
          request, options);
        map.put("status", HttpStatus.BAD_REQUEST);
        map.put("message", "username is required");
        return map;
    }

}

Here, we want the status: BAD_REQUEST and message: “username is required” returned as part of the error attributes when an exception occurs.

Next, let’s implement the Global Error Handler. For this, Spring provides a convenient AbstractErrorWebExceptionHandler class for us to extend and implement in handling global errors:

@Component
@Order(-2)
public class GlobalErrorWebExceptionHandler extends 
    AbstractErrorWebExceptionHandler {

    // constructors

    @Override
    protected RouterFunction<ServerResponse> getRoutingFunction(
      ErrorAttributes errorAttributes) {

        return RouterFunctions.route(
          RequestPredicates.all(), this::renderErrorResponse);
    }

    private Mono<ServerResponse> renderErrorResponse(
       ServerRequest request) {

       Map<String, Object> errorPropertiesMap = getErrorAttributes(request, 
         ErrorAttributeOptions.defaults());

       return ServerResponse.status(HttpStatus.BAD_REQUEST)
         .contentType(MediaType.APPLICATION_JSON)
         .body(BodyInserters.fromValue(errorPropertiesMap));
    }
}

In this example, we set the order of our global error handler to -2. This is to give it a higher priority than the DefaultErrorWebExceptionHandler which is registered at @Order(-1).

The errorAttributes object will be the exact copy of the one that we pass in the Web Exception Handler’s constructor. This should ideally be our customized Error Attributes class.

Then, we’re clearly stating that we want to route all error handling requests to the renderErrorResponse() method.

Finally, we get the error attributes and insert them inside a server response body.

This then produces a JSON response with details of the error, the HTTP status and the exception message for machine clients. For browser clients, it has a ‘whitelabel’ error handler that renders the same data in HTML format. This can, of course, be customized.

5. Conclusion

In this article, we looked at various strategies available for handling errors in a Spring WebFlux project and pointed out where it might be advantageous to use one strategy over another.

As promised, the full source code that accompanies the article is available over on GitHub.