Creating a Whitelabel Error Page in Spring Boot

In the world of web development, providing a seamless user experience is paramount. One aspect of this is ensuring that users are presented with friendly and informative error pages when something goes wrong. In this blog post, we will explore the concept of creating a whitelabel error page in Spring Boot, its importance, and how to implement it effectively.

Understanding the Concept

Spring Boot is a popular framework for building Java-based web applications. By default, Spring Boot provides a basic error page, known as the whitelabel error page, which is displayed when an unhandled exception occurs. While this default page is functional, it is often desirable to customize it to better match the look and feel of your application.

A whitelabel error page is essentially a fallback page that is displayed when an error occurs, and no other error handling mechanism is in place. Customizing this page allows you to provide users with more helpful information and maintain a consistent user experience.

Practical Implementation

Ask your specific question in Mate AI

In Mate you can connect your project, ask questions about your repository, and use AI Agent to solve programming tasks

Let's dive into the step-by-step process of creating a custom whitelabel error page in Spring Boot.

Step 1: Create an HTML Error Page

First, create an HTML file that will serve as your custom error page. Place this file in the src/main/resources/templates directory. For example, create a file named error.html:

<!DOCTYPE html>
<html>
<head>
    <title>Error</title>
</head>
<body>
    <h1>Something went wrong!</h1>
    <p>We are sorry, but an unexpected error occurred.</p>
</body>
</html>

Step 2: Configure the Error Page

Next, configure Spring Boot to use your custom error page. This can be done by creating a WebServerFactoryCustomizer bean in your application. Add the following code to your main application class or a configuration class:

@Bean
public WebServerFactoryCustomizer<ConfigurableWebServerFactory> webServerFactoryCustomizer() {
    return factory -> factory.setErrorPages(Collections.singleton(new ErrorPage(HttpStatus.NOT_FOUND, "/error")));
}

This code snippet tells Spring Boot to use the /error path for handling 404 errors. You can customize this further to handle other HTTP status codes as well.

Step 3: Create an Error Controller

To handle the error path, create a controller that maps to /error. This controller will return the custom error page:

@Controller
public class CustomErrorController implements ErrorController {

    @RequestMapping("/error")
    public String handleError() {
        return "error";
    }

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

In this example, the handleError method returns the name of the error view, which corresponds to the error.html file we created earlier.

Common Pitfalls and Best Practices

When creating a custom whitelabel error page in Spring Boot, there are a few common pitfalls to be aware of:

Not handling all error codes: Ensure that you handle various HTTP status codes, such as 404, 500, etc., to provide a comprehensive error handling solution.
Not providing useful information: While it's important to keep the error page simple, make sure to provide users with enough information to understand what went wrong and what they can do next.
Ignoring security concerns: Avoid displaying sensitive information on the error page that could be exploited by malicious users.

Here are some best practices to follow:

Consistency: Ensure that the custom error page matches the overall design and branding of your application.
Logging: Log the details of the error on the server side to help with debugging and monitoring.
User guidance: Provide clear instructions or links to help users navigate back to a functional part of the application.

Advanced Usage

For more advanced usage, you can create different error pages for different status codes. For example, you can create separate HTML files for 404 and 500 errors:

<!DOCTYPE html>
<html>
<head>
    <title>Page Not Found</title>
</head>
<body>
    <h1>404 - Page Not Found</h1>
    <p>The page you are looking for does not exist.</p>
</body>
</html>

<!DOCTYPE html>
<html>
<head>
    <title>Internal Server Error</title>
</head>
<body>
    <h1>500 - Internal Server Error</h1>
    <p>An unexpected error occurred on the server.</p>
</body>
</html>

Then, update the WebServerFactoryCustomizer bean to handle these specific status codes:

@Bean
public WebServerFactoryCustomizer<ConfigurableWebServerFactory> webServerFactoryCustomizer() {
    return factory -> {
        factory.setErrorPages(Set.of(
            new ErrorPage(HttpStatus.NOT_FOUND, "/404"),
            new ErrorPage(HttpStatus.INTERNAL_SERVER_ERROR, "/500")
        ));
    };
}

And create corresponding controller methods to handle these paths:

@Controller
public class CustomErrorController implements ErrorController {

    @RequestMapping("/404")
    public String handleNotFound() {
        return "404";
    }

    @RequestMapping("/500")
    public String handleServerError() {
        return "500";
    }

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

Conclusion

Creating a custom whitelabel error page in Spring Boot is a straightforward process that can significantly enhance the user experience of your application. By following the steps outlined in this blog post, you can provide users with informative and aesthetically pleasing error pages that align with your application's branding. Remember to handle various error codes, avoid common pitfalls, and follow best practices to ensure a robust error handling solution.

AI agent for developers

Boost your productivity with Mate: easily connect your project, generate code, and debug smarter - all powered by AI.

Do you want to solve problems like this faster? Download now for free.