Generic Top

Get started with Spring 5 and Spring Boot 2, through the Learn Spring course:


1. Overview

In this article, we're going to look at how to disable and customize the default error page for a Spring Boot application as proper error handling depicts professionalism and quality work.

2. Disabling the Whitelabel Error Page

First, let's see how we can disable the white label error page entirely, by setting the server.error.whitelabel.enabled property to false:


Adding this entry to the file will disable the error page and show a concise page that originates from the underlying application container, e.g., Tomcat.

We can achieve the same result by excluding the ErrorMvcAutoConfiguration bean. We can do this by either adding this entry to the properties file:


#for Spring Boot 2.0

Or by adding this annotation to the main class:

@EnableAutoConfiguration(exclude = {ErrorMvcAutoConfiguration.class})

All the methods mentioned above will disable the white label error page. That leaves us with the question of who then actually handles the error?

Well, as mentioned above, it's usually the underlying application container. The good thing is we can further customize things by showing our custom error pages instead of all the defaults – this is the focus of the next section.

3. Displaying Custom Error Pages

We first need to create a custom HTML error page.

We'll save the file as error.html since we're using Thymeleaf template engine:

<!DOCTYPE html>
<h1>Something went wrong! </h1>
<h2>Our Engineers are on it</h2>
<a href="/">Go Home</a>

If we save this file in resources/templates directory, it'll automatically be picked up by the default Spring Boot's BasicErrorController.

This is all we need to display our custom error page. With some styling, we'll now have a much nicer looking error page for our users:


Spring Boot Custom Error Page

We can be more specific by naming the file with the HTTP status code we want it used e.g. saving the file as 404.html in resources/templates/error means it'll be used explicitly for 404 errors.

3.1. A Custom ErrorController

The limitation so far is that we can't run custom logic when errors occur. To achieve that, we have to create an error controller bean that'll replace the default one.

For this, we have to create a class that implements the ErrorController interface. Additionally, we need to set the server.error.path property to return a custom path to call when an error occurred

public class MyErrorController implements ErrorController  {

    public String handleError() {
        //do something like logging
        return "error";

In the snippet above, we also annotate the class with @Controller and create a mapping for the path that is specified as the property server.error.path:


This way the controller can handle calls to the /error path.

In the handleError(), we return the custom error page we created earlier. If we trigger a 404 error now, it's our custom page that will be displayed.

Let's further enhance the handleError() to display specific error pages for different error types.

For example, we can have nicely designed pages specifically for 404 and 500 error types. Then we can use the HTTP status code of the error to determine a suitable error page to display:

public String handleError(HttpServletRequest request) {
    Object status = request.getAttribute(RequestDispatcher.ERROR_STATUS_CODE);
    if (status != null) {
        Integer statusCode = Integer.valueOf(status.toString());
        if(statusCode == HttpStatus.NOT_FOUND.value()) {
            return "error-404";
        else if(statusCode == HttpStatus.INTERNAL_SERVER_ERROR.value()) {
            return "error-500";
    return "error";

Then, for a 404 error, for example, we'll see the error-404.html page:


4. Conclusion

With this information, we can go now handle errors more elegantly and show our users an aesthetic page.

As always, the complete source code is available over on Github.

Generic bottom

Get started with Spring 5 and Spring Boot 2, through the Learn Spring course:

Generic footer banner
Comments are closed on this article!