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> routes(Handler handler) {
    return RouterFunctions.route(RequestPredicates.GET("/hello")
      .and(RequestPredicates.accept(MediaType.TEXT_PLAIN)), 
        handler::handleRequest);
    }

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

public Mono<ServerResponse> handleWithGlobalErrorHandler(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) {
    try {
        return Mono.just("Hello, " + request.queryParam("name").get());
    } catch (Exception e) {
        return Mono.error(e);
    }
}

So long as a username is present as part of our request, e.g., if the endpoint is called as “/hello?username=Tonni“, 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> handleWithErrorReturn(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> handleWithErrorResumeAndDynamicFallback(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> handleWithErrorResumeAndFallbackMethod(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> handleWithErrorResumeAndCustomException(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. It is important to not that the error handling at functional level is applicable for both annotation based configuration as well as with the RouterFunction we used in this article.

Certainly we can use annotations to handle exceptions for our REST API but for this article we’ll opt to handle our WebFlux errors at a global level with a global error handler. 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 the 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 “white-label” error handler that renders the same data in HTML format. This can be customized, of course.

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.