Spring Boot provides a default error page, known as the Whitelabel Error Page, to handle errors and exceptions gracefully. However, you can customize this error page to provide a better user experience and align it with your application's look and feel. This tutorial will explore how to customize the Whitelabel Error Page in a Spring Boot application.

Prerequisites

JDK 17 or later
Maven or Gradle
IDE (IntelliJ IDEA, Eclipse, etc.)

Step 1: Set Up a Spring Boot Project

1.1 Create a New Spring Boot Project

Use Spring Initializr to create a new project with the following dependencies:

Spring Web

Download and unzip the project, then open it in your IDE.

Step 2: Create a Custom Error Page

2.1 Create an HTML Error Page

Create a custom error page named error.html in the src/main/resources/templates directory. This file will be served whenever an error occurs.

<!-- src/main/resources/templates/error.html -->

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Error</title>
    <style>
        body {
            font-family: Arial, sans-serif;
            background-color: #f2f2f2;
            margin: 0;
            padding: 0;
        }
        .container {
            text-align: center;
            padding: 50px;
        }
        h1 {
            font-size: 50px;
            color: #ff0000;
        }
        p {
            font-size: 20px;
        }
    </style>
</head>
<body>
    <div class="container">
        <h1>Error</h1>
        <p>Something went wrong. Please try again later.</p>
    </div>
</body>
</html>

Explanation:

This HTML file will replace the default Whitelabel Error Page.
The file is placed in the templates directory, which is the default location for Thymeleaf templates in Spring Boot.
You can customize the HTML and CSS to match your application's design.

Step 3: Customize Error Handling

3.1 Create a Custom Error Controller

You can create a custom error controller to handle specific error codes or provide more detailed error messages.

package com.example.demo;

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

import jakarta.servlet.RequestDispatcher;
import jakarta.servlet.http.HttpServletRequest;

@Controller
public class CustomErrorController implements ErrorController {

    @GetMapping("/error")
    public String handleError(HttpServletRequest request) {
        Object status = request.getAttribute(RequestDispatcher.ERROR_STATUS_CODE);

        if (status != null) {
            int statusCode = Integer.parseInt(status.toString());

            if (statusCode == 404) {
                return "error-404";
            } else if (statusCode == 500) {
                return "error-500";
            }
        }
        return "error";
    }

    public String getErrorPath() {
        return "/error";
    }
}

Explanation:

@Controller: Marks the class as a Spring MVC controller.
@GetMapping("/error"): Maps the /error path to the handleError method.
HttpServletRequest request: Provides access to the current HTTP request.
RequestDispatcher.ERROR_STATUS_CODE: Retrieves the error status code from the request.
The method returns different views based on the status code (error-404, error-500, etc.).

3.2 Create Additional Error Pages

Create additional error pages for specific status codes if needed. For example, create error-404.html and error-500.html in the src/main/resources/templates directory.

error-404.html

<!-- src/main/resources/templates/error-404.html -->

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Page Not Found</title>
    <style>
        body {
            font-family: Arial, sans-serif;
            background-color: #f2f2f2;
            margin: 0;
            padding: 0;
        }
        .container {
            text-align: center;
            padding: 50px;
        }
        h1 {
            font-size: 50px;
            color: #ff0000;
        }
        p {
            font-size: 20px;
        }
    </style>
</head>
<body>
    <div class="container">
        <h1>404 - Page Not Found</h1>
        <p>The page you are looking for does not exist.</p>
    </div>
</body>
</html>

error-500.html

<!-- src/main/resources/templates/error-500.html -->

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Server Error</title>
    <style>
        body {
            font-family: Arial, sans-serif;
            background-color: #f2f2f2;
            margin: 0;
            padding: 0;
        }
        .container {
            text-align: center;
            padding: 50px;
        }
        h1 {
            font-size: 50px;
            color: #ff0000;
        }
        p {
            font-size: 20px;
        }
    </style>
</head>
<body>
    <div class="container">
        <h1>500 - Server Error</h1>
        <p>An unexpected error occurred. Please try again later.</p>
    </div>
</body>
</html>

Step 4: Running and Testing the Application

4.1 Run the Application

Run the Spring Boot application using your IDE or the command line:

./mvnw spring-boot:run

4.2 Test the Custom Error Pages

Open your browser and navigate to URLs that trigger errors to see the custom error pages in action. For example:

http://localhost:8080/nonexistent should display the custom 404 error page.
Trigger a server error (500) to see the custom 500 error page.

Conclusion

In this tutorial, you have learned how to customize the Whitelabel Error Page in a Spring Boot application. By creating custom error pages and a custom error controller, you can provide a better user experience and ensure your error handling aligns with your application's design. This approach allows you to handle different types of errors and provide meaningful messages to your users.

Related Spring Boot Source Code Examples

Spring Core Annotations with Examples

Spring Boot

Source Code Examples

Search This Blog

Customize Whitelabel Error Page in Spring Boot