Display Custom Error Pages in Spring Boot

This post will discuss how to override the Spring Boot error page with our custom HTML page.

By default, Spring Boot displays a Whitelabel error page if we encounter a server error. To specify the custom error logic, we need a @Controller that handles the /error path or a View that resolves with a name of error. Let’s discuss both approaches in detail:

1. Implementing ErrorController interface

We know that Spring Boot automatically registers the BasicErrorController as a Spring Bean when the implementation of ErrorController is not provided. To replace the default behavior completely, implement the ErrorController interface, and override its getErrorPath() method to return the path of the error page, as shown in the following example.

import org.springframework.boot.web.servlet.error.ErrorController;

import org.springframework.web.bind.annotation.RequestMapping;

import org.springframework.web.bind.annotation.RestController;

@RestController

public class Controller implements ErrorController {

// …

@RequestMapping("/error")

public String handleError() {

return "<h1>Something went wrong!</h1>";

}

@Override

public String getErrorPath() {

return "/error";

}

2. Custom Error Pages

We can also display a custom HTML page for an error.

1. Let’s start by adding Thymeleaf template engine dependency to pom.xml.

<groupId>org.springframework.boot</groupId>

<artifactId>spring-boot-starter-thymeleaf</artifactId>

</dependency>

2. Next, create a custom HTML error page, and label it as error.html.

<!DOCTYPE html>

<html>

</head>

<body>

<h2>Something went wrong and we couldn't complete your request.</h2>

</body>

</html>

3. Place error.html file under resources/templates directory. The folder structure would be as follows:

src/
+- main/
    +- java/
    |   + <source code>
    +- resources/
        +- templates/
            +- error.html

4. Finally, add a bean that implements the ErrorViewResolver interface, as shown in the following example:

import org.springframework.boot.web.servlet.error.ErrorController;

import org.springframework.web.bind.annotation.RequestMapping;

import org.springframework.web.bind.annotation.RestController;

import org.springframework.web.servlet.ModelAndView;

@RestController

public class Controller implements ErrorController {

// …

@RequestMapping("/error")

public ModelAndView handleError()

{

ModelAndView modelAndView = new ModelAndView();

modelAndView.setViewName("error");

return modelAndView;

}

@Override

public String getErrorPath() {

return "/error";

}

We can also display specific error pages for different error types. We can do this by naming the HTML file with the corresponding HTTP status code.

In the following example, different error pages are displayed for different HTTP status codes – error-404.html page for 404 Not Found, error-403.html page for 403 Forbidden, error-500.html page for 500 Internal Server, and error.html page otherwise.

import org.springframework.boot.web.servlet.error.ErrorController;

import org.springframework.http.HttpStatus;

import org.springframework.web.bind.annotation.RequestMapping;

import org.springframework.web.bind.annotation.RestController;

import org.springframework.web.servlet.ModelAndView;

import javax.servlet.http.HttpServletResponse;

@RestController

public class Controller implements ErrorController {

// …

@RequestMapping("/error")

public ModelAndView handleError(HttpServletResponse response)

{

ModelAndView modelAndView = new ModelAndView();

if (response.getStatus() == HttpStatus.NOT_FOUND.value()) {

modelAndView.setViewName("error-404");

}

else if (response.getStatus() == HttpStatus.FORBIDDEN.value()) {

modelAndView.setViewName("error-403");

}

else if (response.getStatus() == HttpStatus.INTERNAL_SERVER_ERROR.value()) {

modelAndView.setViewName("error-500");

}

else {

modelAndView.setViewName("error");

}

return modelAndView;

}

@Override

public String getErrorPath() {

return "/error";

}

That’s all about displaying custom error pages in Spring Boot.