Spring Boot Whitelabel Error Page

by

In this article, we will cover the famous Spring Boot Whitelabel error page. We are covering how to disable the default error page and how we can customize the Whitelabel error page in your Spring Boot application.

 

Introduction

Spring Boot uses a default Whitelabel error page in case server error. This is not very helpful and we may want to give more relevant information to the customer in a production environment. This article focuses on the Spring Boot whitelabel error page. We will learn how to disable this default behavior and how we can use our own custom error page to align with our UI.

 

1. Disabling Whitelabel Error Page

There are multiple ways to disable this behavior in your Spring Boot application. Let’s cover common options to do this.

1.1 Using Properties File

Spring Boot provides an application.properties (or YAML) file to easily configure/change your application. We can use the same property file to disable this error page globally. Set server.error.whitelabel.enabled to false to achieve this.

# Whether to enable the default error page displayed in browsers in case of a server error.
server.error.whitelabel.enabled=false

Please know that using the above configuration will restore the default of the servlet container you are using. This means that if you are not using any custom error page, the default servlet container error page shown to the customer (like default tomcat server error page).

Another option is to exclude ErrorMvcAutoConfiguration from your application using application.properties file.

spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.web.servlet.error.ErrorMvcAutoConfiguration

For Spring Boot 1.x application use ErrorMvcAutoConfiguration in exclude the list.

1.2 Exclude using @EnableAutoConfiguration

In case you like to exclude using the code, you have the option to pass exclude configuration list to the @EnableAutoConfiguration annotation.

@SpringBootApplication
@EnableAutoConfiguration(exclude = {
 ErrorMvcAutoConfiguration.class
})
public class SpringBootApplication { //application code 
}

 

2. Custom Error Page

As suggested, one of the first options is to Overriding the error page with your own template. For this post, we are taking Thymeleaf as our underlying templating engine. We create a custom error page with name error.html and save it under resources/templates directory. In case of error, Spring Boot system will automatically pick this custom error page. Let’s see how the page looks like before customizing error page.

Default Whitelabel Error Page

Let’s create our custom error.html and place it under the <em>resources/templates</em> directory.

<!DOCTYPE html>
<html lang="en">
   <head>
      <title>We've got some trouble</title>
   </head>
   <body>
      <div class="cover">
         <h1>Our apologies.</h1>
         <p class="lead">This page stepped out for a quick ride.</p>
         <p>Please go back to our homepage to restart your browsing experience.</p>
      </div>
   </body>
</html>

If we run our application, this is how the output shown to the customer.

Custom Error Page

Once we add the error.html in the templates directory, Spring Boot BasicErrorController automatically pick our custom template.

 

3. Custom ErrorController

If the above options are not suitable for your need or if we want to have a better control on the error handling mechanism, we have the option to extend Spring’s ErrorController with our own implementation. We need to implement the ErrorController interface and overrides its getErrorPath()to return a custom path.

package com.javadevjournal.controller;

import org.springframework.boot.web.servlet.error.ErrorController;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;

@Controller
public class CustomErrorController implements ErrorController {

 private static final String PATH = "/error";

 @RequestMapping(value = PATH)
 public String error() {
  return "customError";
 }

 @Override
 public String getErrorPath() {
  return PATH;
 }
}

Let’s have a look at the above code.

  • Our controller creates a mapping for the path as returned by getErrorPath() method.
  • ErrorController interface shows that a @Controller is used to render errors.
  • We have the option to use getErrorPath() to return different error pages based on the error type.

Let’s create a new error page which we will use in this new controller method.

<!DOCTYPE html>
<html lang="en">
   <head>
      <title>We've got some trouble</title>
   </head>
   <body>
      <div class="cover">
         <h1>Our apologies For Custom Page.</h1>
         <p class="lead">This page stepped out for a quick ride.</p>
         <p>Please go back to our homepage to restart your browsing experience.</p>
      </div>
   </body>
</html>

When we run our application this time, we will have a different error page displayed to the customer.

Custom Error Page

 

Summary

In this post, we cover how to disable Spring Boot Whitelabel error page and how we can customize the Whitelabel error page in your Spring Boot application. We learned how to extend the error handling mechanism by implementing ErrorController in the custom error handling controller.