Ebooks

Spring Boot Whitelabel Error

Spring Boot Whitelabel Error tutorial shows how to configuare and display error messages in a Spring Boot application.

Spring is a popular Java application framework and Spring Boot is an evolution of Spring which helps create stand-alone, production-grade Spring based applications easily.

WhiteLabel Error Page

WhiteLabel Error Page is a generic Spring Boot error page that is displayed when no custom error page is present.

server.error.whitelabel.enabled=false

A WhiteLabel Error can is disabled in the application.properties file by setting the server.error.whitelabel.enabled to false.

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

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

@SpringBootApplication(exclude = {ErrorMvcAutoConfiguration.class})
public class Application {

Alternatively, the exclusion can be done in an annotation.

When the WhiteLabel Error Page is disabled and no custom error page is provided, the web server's error page (Tomcat, Jetty) is shown.

Spring Boot Custom Error Page

Without using a Thymeleaf template engine, we can place a generic custom error page in a src/main/resources/public/errors directory.

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; - public
</p>

</body>
</html>

This is a generic error page for 404 error.

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 administrator; - template generic
</p>

</body>
</html>

A generic error page using a template can be placed in the src/main/resources/templates/ directory.

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; template - specific
</p>

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

</body>
</html>

A specific error page using a template can be placed in the src/main/resources/templates/error/ directory.

Spring Boot Custom Error Page example

In the following example we create a simple Spring Boot application with uses a custom error page for the 404 error.

pom.xml
src
├───main
│   ├───java
│   │   └───com
│   │       └───zetcode
│   │           │   Application.java
│   │           └───controller
│   │                   MyController.java
│   └───resources
│       │   application.properties
│       └───templates
│           └───error
│                   404.html
└───test
    └───java

This is the project structure of the Spring application.

pom.xml
<?xml version="1.0" encoding="UTF-8"?>
<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.zetcode</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>

This is the Maven pom.xml file. We have the spring-boot-starter-web and spring-boot-starter-thymeleaf.

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

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

com/zetcode/controller/MyController.java
package com.zetcode.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";
    }
}

We have a simple controller that returns a text message for a home page.

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; template - specific
</p>

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

</body>
</html>

This is a custom template error page created with Thymeleaf.

com/zetcode/Application.java
package com.zetcode;

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);
    }
}

This code sets up the Spring Boot application.

In this tutorial, we have covered the WhiteLabel Error and we showed how to create our custom error pages.

List all Spring Boot tutorials.