Whitelabel Error Page Spring Boot Configuration

Spring Boot installs a “whitelabel” error page which you see in a browser client if you encounter a server error. Whitelabel Error Page is a generic Spring Boot error page which is displayed when no custom error page is found.

Set “server.error.whitelabel.enabled=false” to switch off the default error page.

Another way of disabling the WhiteLabel Error is by excluding the ErrorMvcAutoConfiguration.

By doing this it restores the default servlet container that you are using. But Spring Boot still tries to resolve the error view, so you should add your own error page instead of disabling it completely.

Overriding the error page with your own error page depends on the template technology you use. For example if you are using Thymeleaf, then you can add an error.html template. If you are using FreeMarker, then you can add an error.ftlh template. Generally, you need a view which resolves with name of error or @Controller which handles the error path.

Template Engines

As well as in REST web services, you can also use Spring MVC to provide dynamic HTML content. Spring MVC supports a various template technologies, like Thymeleaf, FreeMarker, and JSPs. Spring Boot has auto-configuration support for following template engines:

If possible, use of JSP should be avoided. There are many limitations when using them with embedded servlet containers.

When you use one of these template engines with the default configuration then your templates are used up automatically from path : src/main/resources/templates.

In a default way Spring Boot provides /error mapping which handles all errors in intelligent way, and that is registered as β€œglobal” error page in servlet container.

For webservices , it produces a JSON response along with details of the error, HTTP status and the exception message.

For browser clients, it has β€œwhitelabel” error view which renders the same data in HTML format.

Spring Boot Custom Error Page

If not using Thymeleaf template engine then you can place a generic custom error page in  src/main/resources/public/errors directory.

Generic error page for 404 error : resources/public/errors/404.html

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>404 - Resource not found</title>
</head>
<body>

<h2>404 - Resource not found</h2>

<p>
The requested resource was not found
</p>

</body>
</html>

Generic error page using template can be placed in directory src/main/resources/templates/

resources/templates/error.html

<!DOCTYPE html>
<html>
<head>
    <title>Error Occurred</title>
</head>
<body>
<h1>Error Occurred</h1>

<p>
    An error has occurred. Please contact the Admin
</p>

</body>
</html>

Specific error page using a template is placed in directory.  src/main/resources/templates/error/ 

resources/templates/error/404.html

<!DOCTYPE html>
<html lang="en">
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>404 - Resource not found</title>
</head>
<body>

<h2>404 - Resource not found</h2>

<p>
The requested resource was not found
</p>

<p th:text="${error}">Error Info</p>
<p th:text="${status}">Status</p>

</body>
</html>

Spring Boot Custom Error Page example

In the this example we will create a simple Spring Boot application which uses a custom error page for 404 error.

src
β”œβ”€β”€β”€main
β”‚   β”œβ”€β”€β”€java
β”‚   β”‚   └───com
β”‚   β”‚       └───techblogstation
β”‚   β”‚           β”‚   Application.java
β”‚   β”‚           └───controller
β”‚   β”‚                   MyController.java
β”‚   └───resources
β”‚       β”‚   application.properties
β”‚       └───templates
β”‚           └───error
β”‚                   404.html
└───test
    └───java

pom.xml

<project xmlns="http://maven.apache.org/POM/4.0.0"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
    <groupId>com.techblogstation</groupId>
    <artifactId>springbootwhitelabelerror</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>jar</packaging>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <maven.compiler.source>11</maven.compiler.source>
        <maven.compiler.target>11</maven.compiler.target>
    </properties>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.1.7.RELEASE</version>
    </parent>

    <dependencies>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-thymeleaf</artifactId>
        </dependency>

    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>

In application.properties, we turn off the WhiteLabel Error with one of these settings. If we provide a custom error page, it automatically takes preference over the WhiteLabel Error.

application.properties

#server.error.whitelabel.enabled=false
#spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.web.servlet.error.ErrorMvcAutoConfiguration

We have created a controller which returns a text message for a home page.

package com.techblogstation.controller;

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

@RestController
public class MyController {

    @GetMapping("/")
    public String home() {

        return "Home page";
    }
}

Below we have created a custom template error page created using Thymeleaf.

<!DOCTYPE html>
<html lang="en">
<html xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>404 - resource not found</title>
</head>
<body>

<h2>404 - Resource not found</h2>

<p>
The requested resource was not found
</p>

<p th:text="${error}">Error Info</p>
<p th:text="${status}">Status</p>

</body>
</html>

Main Spring Boot application class

package com.techblogstation;

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

@SpringBootApplication
public class Application  {

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

Conclusion

In this example, we have covered the WhiteLabel Error spring boot configuration and we explained how to create our custom error pages. Also we have explained various template engines.

Newsletter Updates

Enter your name and email address below to subscribe to our newsletter

Leave a Reply