In this tutorial I am going to discuss about what is Whitelabel Error Page and how to deal with Whitelabel Error Page in Spring Boot applications. Spring boot allows you to setup a Spring based application with minimal configurations. Spring MVC applications provide no default (fall-back) error page out of the box but Spring Boot based applications provide a fall-back error page for handling errors. If you want to handle error in Spring based application then you have to set the default error page using SimpleMappingExceptionResolver.

When an error or exception occurs Spring boot tries to find a mapping for /error. What this means is a URL ending in /error maps to a logical view with the same name error. This error actually maps to the file name error.html if you are using Thymeleaf template or error.jsp if you are using JSP page as a view for your application. This view is returned according to the setup of your InternalResourceViewResolver.

Now if no view-resolver mapping for /error is found then Spring boot defines its own fallback error page which is called Whitelabel Error Page. This Whitelabel Error Page is basically a minimal page with the HTTP status information and any error details, such as the message from an uncaught exception.

Let’s understand the above scenario using Spring boot example. Let’s say you have the following Spring boot main class. Make sure you have the spring-boot-starter-web dependency in your application.

package com.roytuts.spring.boot.whitelabel.error.page;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class SpringBootWhiteLabelErrorPageApp {

	public static void main(String[] args) {
		SpringApplication.run(SpringBootWhiteLabelErrorPageApp.class, args);
	}

}

Once you run the above main class, your application gets deployed into embedded Tomcat server and runs on localhost and port 8080. If you try to access the URL http://localhost:8080/ in the browser then you will see the following Whitelabel Error Page on the browser:

So why was the above error information shown to you? Because the page you are trying to access is not found and you have not mapped any error page for /error endpoint.

Even if you try to access any other endpoint that does not exist in the application will give you the same error. Even if you define a REST controller and try to access an endpoint that does not exist, you will see the same error information. But for any server error you will see different status (5xx -> for example 500, 501, etc.) and different error type.

If you are making REST call Spring boot returns a JSON representation response of the same error information that is put in the Whitelabel error page.

Now let’s add an error page error.html under the classpath folder src/main/resources/templates. The error.html page has the following simple content. Makes sure you have the spring-boot-starter-thymeleaf dependency in your application.

<h1>Error Page</h1>
<p>Application has encountered a problem. Please contact support ...</p>

Now when you try to access endpoint that does not exist on your server will give you the following error information:

The above page will not be shown in RESTful request because in REST request the JSON response is returned by default.

You can download the sample application.