If you’ve worked with Spring Boot or web applications, chances are you’ve encountered the Whitelabel Error Page. This error page often appears when something goes wrong with your Spring Boot application, leaving developers and users alike scratching their heads. But don’t worry—understanding what the Whitelabel Error Page is and how to fix it is relatively simple.
In this comprehensive guide, we’ll walk you through everything you need to know about the Whitelabel Error Page, including its causes, how to disable it, and how to customize it in Spring Boot.
What is a Whitelabel Error Page?
A Whitelabel Error Page is a generic error page that appears when there is an issue with your web application, but no custom error page is configured. It’s a default error page provided by Spring Boot. Instead of giving users a blank page or a browser-specific error, Spring Boot generates this default Whitelabel Error Page to provide some basic information about the error.
The Whitelabel Error Page typically shows up when there’s a 404 (Not Found), 500 (Internal Server Error), or another HTTP error that occurs during the application’s runtime. The goal is to give some insight into what went wrong without exposing too much detail about your application.
What is a Whitelabel Error Page in Spring Boot?
In Spring Boot, the Whitelabel Error Page is a fallback error page provided when no other error handling is specified. Spring Boot automatically creates this page to provide basic information about the error, such as the HTTP status code and a brief description of the error.
Why Do I Get a Whitelabel Error Page in Spring Boot?
When you see the Whitelabel Error Page in Spring Boot, it means that an error has occurred, and Spring Boot cannot find a custom error page to display. There are a few common reasons why this might happen:
- 404 Error (Page Not Found): If the user tries to access a URL that doesn’t exist in your application, Spring Boot will display the Whitelabel Error Page with a 404 status.
- 500 Error (Internal Server Error): When there’s a server-side issue, such as an unhandled exception, the 500 error occurs, and the Whitelabel Error Page is displayed.
- No Custom Error Page Configured: Spring Boot uses the Whitelabel Error Page when there is no custom error page defined in the application. By default, Spring Boot doesn’t generate custom error pages for all possible errors unless explicitly configured to do so.
How to Disable the Whitelabel Error Page in Spring Boot
If you prefer not to use the Whitelabel Error Page, Spring Boot allows you to disable it easily. Disabling the page ensures that users don’t see the generic error page and forces the application to handle errors more gracefully.
To disable the Whitelabel Error Page, add the following property to your application.properties or application.yml file:
In application.properties:
server.error.whitelabel.enabled=false
In application.yml:
server:
error:
whitelabel:
enabled: false
Once this property is set to false, Spring Boot will no longer display the Whitelabel Error Page. Instead, the application will return a blank page or a browser-generated error unless a custom error page is configured.
Customizing the Whitelabel Error Page in Spring Boot
Rather than disabling the Whitelabel Error Page, you can choose to customize it to fit your application’s branding and messaging. Customizing the error page allows you to provide more helpful information to users or make the error page more aesthetically pleasing.
To customize the error page, you need to create an error.html file and place it in the src/main/resources/templates directory. Spring Boot will automatically serve this page whenever an error occurs.
Here’s a simple example of a custom error page:
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Error</title>
</head>
<body>
<h1>Oops! Something went wrong.</h1>
<p>We couldn't find the page you're looking for.</p>
<a href="/">Go back to the homepage</a>
</body>
</html>
This custom error page will replace the Whitelabel Error Page whenever an error occurs in your Spring Boot application.
Handling Specific Error Codes in Spring Boot
Sometimes, you want to show different error pages for different error codes, such as 404 (Not Found) and 500 (Internal Server Error). Spring Boot makes it easy to handle specific error codes by creating separate error pages for each code.
To handle specific error codes, create custom error pages like error-404.html and error-500.html in the src/main/resources/templates directory. Spring Boot will automatically serve the appropriate page based on the HTTP status code.
For example, to handle 404 errors with a custom page, create an error-404.html file:
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Page Not Found</title>
</head>
<body>
<h1>404 - Page Not Found</h1>
<p>We couldn't find the page you're looking for. Please check the URL and try again.</p>
<a href="/">Go back to the homepage</a>
</body>
</html>
Similarly, you can create a custom 500 error page for server-side errors.
Advanced Error Handling with @ControllerAdvice
For more control over error handling in Spring Boot, you can use the @ControllerAdvice annotation. This allows you to handle exceptions and errors programmatically and provide custom responses based on the error type.
Here’s an example of how to use @ControllerAdvice to handle errors:
import org.springframework.http.HttpStatus;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.ControllerAdvice;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.ResponseStatus;public class GlobalExceptionHandler {
public String handleNotFoundException(Exception e, Model model) {
model.addAttribute(“errorMessage”, “Page not found”);
return “error”;
}
}
With @ControllerAdvice, you can capture specific exceptions and provide custom responses or error pages depending on the error.
Common Reasons for Whitelabel Error Page in Spring Boot
The Whitelabel Error Page can show up for several reasons in a Spring Boot application:
- Invalid URL: A user may try to access a URL that doesn’t exist, leading to a 404 error.
- Uncaught Exceptions: If an exception is thrown and not handled by the application, the 500 error page will appear.
- Missing Templates: If you’ve configured custom templates but they’re missing or named incorrectly, Spring Boot will revert to the Whitelabel Error Page.
- Misconfigured Routes: Improper routing in your Spring Boot application can result in the Whitelabel Error Page appearing if the app can’t find the correct controller to handle the request.
FAQs About Whitelabel Error Page
1. What is a Whitelabel Error Page?
A Whitelabel Error Page is a generic error page provided by Spring Boot when no custom error page is configured. It appears when an error, like a 404 or 500, occurs in the application.
2. Why am I getting a Whitelabel Error Page in Spring Boot?
You may see the Whitelabel Error Page if an error occurs, such as a missing page (404) or an internal server issue (500), and no custom error handling is configured.
3. How do I disable the Whitelabel Error Page?
To disable the Whitelabel Error Page, add server.error.whitelabel.enabled=false to your application.properties or application.yml file.
4. How do I customize the Whitelabel Error Page?
You can customize the Whitelabel Error Page by creating a custom error page, like error.html, in the src/main/resources/templates directory.
5. What is Spring Boot Whitelabel Error Page?
In Spring Boot, the Whitelabel Error Page is a default error page that provides basic information about an error when no custom error page is specified.
6. How do I create custom error pages for specific error codes?
To create custom error pages for specific error codes, like 404 or 500, create error-404.html or error-500.html in the src/main/resources/templates directory.
7. Can I handle errors programmatically in Spring Boot?
Yes, you can handle errors programmatically in Spring Boot using @ControllerAdvice to catch specific exceptions and return custom responses.
8. How do I handle 404 errors in Spring Boot?
To handle 404 errors, create a custom error-404.html page or use @ControllerAdvice to capture and handle NotFoundExceptions.
9. Why is my custom error page not showing up?
If your custom error page isn’t showing up, ensure that the file is correctly named and placed in the src/main/resources/templates directory. Also, verify that the file path and content are correct.
10. What are common causes of the Whitelabel Error Page?
Common causes include invalid URLs, unhandled exceptions, missing templates, and misconfigured routes.
Conclusion
The Whitelabel Error Page in Spring Boot is a helpful feature for developers, providing basic error information when something goes wrong in the application. However, it’s not always the best user experience. Fortunately, Spring Boot makes it easy to disable, customize, or enhance the Whitelabel Error Page to fit your application’s needs.
Whether you’re a beginner learning about Spring Boot or a seasoned developer, understanding how to manage the Whitelabel Error Page is a valuable skill. It allows you to provide a better user experience, manage errors more effectively, and maintain control over your application’s error handling.
By following the steps outlined in this guide, you can customize and control the Whitelabel Error Page to suit your web application’s needs.
