Spring Boot Whitelabel Error
last modified July 16, 2023
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.
<!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.
<!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.
<!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.
build.gradle
...
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.
plugins {
id 'org.springframework.boot' version '3.1.1'
id 'io.spring.dependency-management' version '1.1.0'
id 'java'
}
group = 'com.zetcode'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '17'
repositories {
mavenCentral()
}
dependencies {
implementation 'org.springframework.boot:spring-boot-starter-web'
implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'
}
test {
useJUnitPlatform()
}
This is the Gradle build file. We have the spring-boot-starter-web
and spring-boot-starter-thymeleaf starters.
#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.
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.
<!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.
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 article we have covered the WhiteLabel Error and we showed how to create our custom error pages.