When working with Spring Boot, encountering the “Whitelabel Error Page” can be a frustrating experience, especially for developers in production environments. This generic error page is displayed by default when Spring Boot encounters an unhandled error or exception. While it serves as a simple fallback, it can be rather unhelpful and undesirable in live applications. Fortunately, there are ways to customize or remove the Whitelabel Error Page entirely.
In this article, we’ll explore what the Whitelabel Error Page is, why it appears, and how to disable or replace it with more user-friendly error handling in Spring Boot applications.
What is the Whitelabel Error Page?
The Whitelabel Error Page is a default error page provided by Spring Boot when an error occurs, and no custom error page or handler has been defined. It typically appears with a message like:
vbnet
Whitelabel Error Page
This application has no explicit mapping for /error, so you are seeing this as a fallback.
This page is a part of Spring Boot’s built-in error handling mechanism. While it is useful for quick debugging during development, it doesn’t provide much detail for end users, especially in production environments. It may also expose sensitive information, making it undesirable for deployed applications.
Common Causes of the Whitelabel Error Page
Several scenarios can trigger the Whitelabel Error Page, including:
1. 404 Not Found: When a requested URL doesn’t map to any controller or handler.
2. 500 Internal Server Error: When an exception occurs that isn’t explicitly handled in the code.
3. Unhandled Exceptions: When a runtime exception occurs and no global exception handler exists.
How to Remove or Customize the Whitelabel Error Page
To improve the user experience and remove the default Whitelabel Error Page, Spring Boot provides several options for handling errors more gracefully.
1. Disabling the Whitelabel Error Page
In some cases, you may simply want to disable the Whitelabel Error Page and avoid showing it entirely. This can be done by setting the following property in your `application.properties` or `application.yml` file:
Using `application.properties`
properties
server.error.whitelabel.enabled=false
Using `application.yml`
yaml
server:
error:
whitelabel:
enabled: false
Setting this property to `false` prevents Spring Boot from showing the default Whitelabel Error Page when an error occurs. If you choose this approach, Spring Boot will either show the standard HTTP error response (e.g., `404` or `500`) or redirect to a custom error page, depending on how you’ve configured error handling.
2. Creating a Custom Error Page
To replace the Whitelabel Error Page with a more user-friendly custom page, you can create your own HTML page to handle specific errors. For example, you can create an error page to display when a `404 Not Found` or `500 Internal Server Error` occurs.
Step-by-Step Process:
1. Create a Custom Error HTML Page
Create an HTML file in `src/main/resources/templates/` called `error.html` or `error-404.html`, depending on the error code you want to handle.
Example `error.html`:
html
<!DOCTYPE html>
<html>
<head>
<title>Error</title>
</head>
<body>
<h1>Oops! Something went wrong.</h1>
<p>We couldn’t find the page you’re looking for. Please try again later.</p>
</body>
</html>
2. Handle Specific Errors in application.properties
You can specify custom error pages for specific HTTP error codes by creating corresponding HTML files in the `src/main/resources/templates/` directory. For example:
– error-404.html` for a `404 Not Found
– error-500.html` for a `500 Internal Server Error
3. Spring Boot’s Error Handling Mechanism
If you need more control over error handling, you can use Spring Boot’s `@ControllerAdvice` or implement custom error handling logic in a controller using the `@ExceptionHandler` annotation.
For example, you can create a controller to handle errors globally:
java
@ControllerAdvice
public class GlobalExceptionHandler {@ExceptionHandler(Exception.class)
public String handleException(Exception e) {
// log the exception
return “error”; // This will return the error.html page
}
}
3. Using `ErrorController` to Customize Error Handling
Spring Boot also allows you to implement a custom `ErrorController` to control how errors are handled.
1. Implement `ErrorController` Interface
You can create a class that implements the `ErrorController` interface, providing a custom mapping for the `/error` endpoint.
java
@Controller
public class CustomErrorController implements ErrorController {@RequestMapping(“/error”)
public String handleError(HttpServletRequest request) {
// You can add more logic here to check the status code and return specific error pages
return “custom-error”; // This points to custom-error.html or custom error handling logic
}@Override
public String getErrorPath() {
return “/error”; // Default error path
}
}
2. Create a `custom-error.html` Page
If the error handler above redirects to a `custom-error.html` page, you can place that in the `src/main/resources/templates/` directory to be rendered in case of an error.
4. Error Handling with @ResponseStatus
If you want more granular control over specific exceptions, you can use the `@ResponseStatus` annotation to specify the HTTP status code for different exceptions.
Example:
java
@ResponseStatus(HttpStatus.NOT_FOUND)
public class ResourceNotFoundException extends RuntimeException {
public ResourceNotFoundException(String message) {
super(message);
}
}
This approach ensures that specific exceptions trigger the correct HTTP status, and you can combine it with a custom `@ControllerAdvice` to handle the exception in a user-friendly way.
Conclusion
The Whitelabel Error Page in Spring Boot is a helpful feature during development but can be undesirable in production environments. Disabling it, creating custom error pages, or implementing custom error handling with controllers or `@ControllerAdvice` can significantly improve the user experience. By following the steps outlined in this article by hire tech firms, you can tailor error handling to meet the needs of your application and ensure a smoother user experience when things go wrong.