Spring Boot is widely recognized for its streamlined setup and production-ready defaults, but developers often encounter one persistent issue during development: the Whitelabel Error Page. This error page appears as a generic response whenever something goes wrong in your Spring Boot application, especially when proper error handling and mapping haven’t been configured. While it serves a purpose during development, it can become frustrating without clear understanding of its cause and resolution methods.
TL;DR
The Whitelabel Error Page in Spring Boot typically appears when no custom error page or controller exists to handle unexpected exceptions or missing routes. It can be resolved by creating a custom error controller, properly setting error properties in application.properties, or simply disabling it. The Whitelabel page is Spring Boot’s way of saying, “Something went wrong, and there’s no handler for it”. Avoid it in production by implementing clean error handling.
What is the Whitelabel Error Page?
The Whitelabel Error Page is Spring Boot’s default fallback error display. It is rendered when no appropriate error view or handler is defined. It typically shows an unstyled HTML message such as “There was an unexpected error (type=Not Found, status=404)”. Although this is useful for debugging, it’s not ideal for user-facing applications.
You can encounter this page in different situations:
- The requested URL does not match any controller.
- Your controller throws an unhandled exception.
- The error is not mapped to a specific response view or handler.
Causes of the Whitelabel Error Page
Here are the most common causes leading to this default error page display:
- Missing or incorrect controller mappings: The URL path doesn’t exist or doesn’t match the defined mapping.
- Application exceptions: Uncaught exceptions during the execution of your request handling logic.
- No error view in templates: Spring Boot doesn’t find an error page template like
error.htmlin theresources/templatesfolder. - Default behaviors in Spring Boot: Spring Boot auto-configures the default error page unless it is explicitly overridden or disabled.
How to Fix the Whitelabel Error Page
There are several ways to prevent or replace the Whitelabel Error Page in Spring Boot:
1. Create a Custom Error Page
You can define your own error.html in the /resources/templates directory. Spring Boot will automatically look for this template when an error occurs and render it instead of the Whitelabel Error Page. If you are using Thymeleaf, this method works particularly well.
resources/templates/error.html
<!DOCTYPE html>
<html xmlns:th="http://www.thymeleaf.org">
<head>
<title>Error Page</title>
</head>
<body>
<h1>Oops! Something went wrong.</h1>
<p th:text="${error}"/>
</body>
</html>
2. Disable Whitelabel Error Page
If you simply don’t want the Whitelabel Error Page to show (for example, in production environments), disable it in application.properties:
spring.main.whitelabel.enabled=false
Note, however, that this will disable the fallback page entirely. You must then provide either a custom error handler or a static error page.
3. Implement a Custom ErrorController
You can take full control by creating a class that implements the ErrorController interface. This allows you to handle specific types of errors or customize the response dynamically.
import org.springframework.boot.web.servlet.error.ErrorController;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
@RestController
public class MyErrorController implements ErrorController {
@RequestMapping("/error")
public String handleError() {
return "Custom Error Handling Message";
}
}
Be mindful: in newer Spring Boot versions, the ErrorController interface may be marked as deprecated, and you might need to use other mechanisms via @ControllerAdvice or ErrorViewResolver.
4. Use ControllerAdvice for Exception Handling
Spring’s @ControllerAdvice allows you to globally handle specific exceptions and return meaningful responses. This helps replace the default page based on exception types.
@ControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(Exception.class)
public ResponseEntity<String> handleException(Exception e) {
return new ResponseEntity<>("Custom error: " + e.getMessage(), HttpStatus.INTERNAL_SERVER_ERROR);
}
}
5. Ensure Static and Template Pages Are Properly Positioned
Spring Boot expects static content under resources/static and templates under resources/templates.
If these aren’t correctly positioned, Spring won’t find them and will revert to the Whitelabel Error Page.
Best Practices for Error Handling in Spring Boot
Some best practices to follow for avoiding or customizing the Whitelabel Error Page include:
- Always define an
error.htmltemplate in Thymeleaf-based applications. - Use
@ControllerAdviceto centrally handle all exceptions logically. - Disable the Whitelabel only if you’ve put in place your own comprehensive error recovery strategy.
- Implement logging when handling errors to help with debugging.
- Handle common statuses like 404 and 500 explicitly with friendly user messages.
Additional Configuration Tips
In your application.properties or application.yml, you can also tweak other error settings:
server.error.path=/error server.error.include-message=always server.error.include-binding-errors=always server.error.include-exception=true
These settings give you more control over what details get shown when an error occurs. For example, including exception messages can help you debug during development.
Conclusion
The Whitelabel Error Page isn’t a bug; it’s an intentional design by Spring Boot to signal that an error has happened and hasn’t been properly addressed. While convenient during development, it’s essential to handle errors gracefully in production to improve user experience and application reliability. Whether you opt for custom templates, controller-based handling, or disable it entirely, taking control over application errors is a sign of a mature development practice.
FAQ
- Q: What triggers the Whitelabel Error Page?
A: It appears when an error occurs and no custom error handler or page is provided. - Q: Can I completely disable the Whitelabel Error Page?
A: Yes, by settingspring.main.whitelabel.enabled=falsein yourapplication.properties. - Q: Is creating
error.htmlmandatory to remove the Whitelabel page?
A: No, you can instead use@ControllerAdviceor a custom implementation ofErrorController. - Q: Can I show different error messages for different statuses like 404 or 500?
A: Yes, either by customizingErrorViewResolveror through targeted exception handling with@ControllerAdvice. - Q: Does Spring Boot display the full stack trace by default?
A: No. You can enable it during development by configuringserver.error.include-stacktrace=always.