Whitelabel error page что это

Introduction

Spring Boot, a significant project in the Spring Framework universe, has been a boon for Java developers worldwide, simplifying the task of creating stand-alone, production-grade Spring applications. In a nutshell, it makes it easy to just “run”. Among its extensive feature set, Spring Boot’s default error handling, also known as “WhiteLabel Error Handling”, is a standout. This blog post will deep-dive into Spring Boot’s WhiteLabel Error handling, providing insights into its functionalities, how to customize it, and its overall significance in the development process.

What is WhiteLabel Error Handling?

In Spring Boot, the term “whitelabel” refers to the default behavior of a service. In the case of error handling, the “WhiteLabel Error Page” is the default page that is displayed when an exception occurs. For instance, when you encounter a “404 Not Found” error or a “500 Internal Server Error”, Spring Boot automatically displays a basic error page. This is all thanks to the WhiteLabel error handling mechanism that comes out of the box with Spring Boot.

The Underlying Mechanism

The WhiteLabel error handling mechanism is an implementation of the ErrorController, an interface in the Spring Boot framework. This interface, by default, is overridden by the BasicErrorController that provides the white-label error handling functionality.

Whitelabel Error Page in Spring Boot | Complete Guide

Let’s learn about the Whitelabel error page in Spring Boot and how to customize or disable them. White label error pages are default behavior from Spring Boot. Like any other feature, We can customize this feature to great extent.

What are Whitelabel error pages in Spring Boot?

Depending on API client request or browser request, spring boot provides an error JSON response or a full HTML error page. For example, let’s create a simple /hello endpoint that throws an exception always.

Even though this page looks simple, you can add details to it using the following configuration.

Even though the messages are helpful, this page may not fit well with your other page designs. So if you want to override this page with your own design, you are in luck.

Overriding Whitelabel Error Pages

Spring boot provides a /error mapping at a global servlet container level. This mapping handles requests and sends back JSON or HTML view as a response with error codes/messages. But the view that we saw above looks default. If you notice the first line of the error page, it says “This application has no explicit mapping for /error, so you are seeing this as a fallback.”

Here, the spring boot is trying to hint to you that you need to provide your own template to handle these error requests. So let’s see how to do that.

As we know, The handler mapped for /error expects a view to show the HTML response. If it doesn’t find a view matching “error” it will use the placeholder we have seen above. So we first need to add a template called error.html. But the template alone will not work. You also need to add one of the spring boot supported template engines. In our case, we are adding thymeleaf.

Next, you need to add the error.html template into your src/main/resources/templates directory.

With the above in place, the following MVC attributes will be available for you to access in the templates.

1. message – Return value of exception.getMessage()
2. exception – A string that contains the canonical exception name.
3. trace – The complete stacktrace of the exception that caused this error.
4. errors – A list of validation failures that occured during the request.

Along with these, there is also a status attribute that gives the HTTP status code for the error response. With that in place, we can rewrite our template file to show all these attributes.

This simple template will yield the following error page when we access /hello.

With a little bit of CSS, we can get this page to look better and more appealing.

Disabling Whitelabel error page altogether /Tomcat whitelabel

Spring boot also provides a way to disable the Whitelabel error page altogether using server.error.whitelabel.enabled setting. When set to false, the server will show an error page specific to the servlet container(tomcat). For example, the below error page from tomcat will be visible if the Whitelabel is disabled and no error template is available.

You can swap tomcat with jetty and you will still see an error page like this offered by the jetty runtime. And undertow currently doesn’t provide a view. But it does send response codes.

Important things to note

Always use a custom error.html page for the following reasons.

1. Default whitelabel page lets hackers know you are using spring boot. This means they only need to try the exploits for spring boot.
2. Never show exceptions in your production servers. Exceptions are great info for hackers.
3. A custom error page with proper CSS will blend in to your other pages. You can even provide links and search boxes that can redirect users back to your site.

You can hide specific error attributes based on the configuration we saw earlier. Also, all these configurations are also applicable for the JSON response as well. If your request contains Accept: application/json header, then the response will be in the form of JSON. Even here, you can access all these attributes. For example, take a look at the below request.

Here you can see the trace, exception, and message attributes being available as JSON.

Why do I always get Whitelabel Error Page with status "404" while running a simple Spring Boot Application

This application has no explicit mapping for /error, so you are seeing this as a fallback.

Wed Sep 21 21:34:18 EDT 2016 There was an unexpected error (type=Not Found, status=404). ]/WEB-INF/jsp/welcome.jsp

My application.properties

Please help me. Thanks!

6 Answers 6

This is one of most common error that almost all the spring boot beginners face.

Solution to this is very simple, — your Bootstrap class should know the package or the class path where it should refer in order access the component/controller. Hence you need to specify like :- @ComponentScan(basePackages= <"org.test.controller">)

P.S.- here «org.test.controller» is a qualified name of the package where I have kept my controller.

Figured it out myself.

When I converted my dynamic webproject into maven project it did not create the folder structure this way

I manually created myself and moved the jsp files from WebContent/WEB-INF/jsp to src/main/webapp/WEB-INF/jsp and modified the Java build path in the project properties.

Then I restarted the embedded tomcat and tried it again. It worked.

General troubleshooting guide for the Whitelabel error page:

Enable trace logging for the Spring web handling. Add to your application.properties : logging.level.org.springframework.web.*=TRACE

With this you can see during startup if your controller is registered properly. For example having HelloController with one mapped GET method you should see on logs:

If you see your controller methods logged, it is registered properly. If not, follow the other advices given for correct project structure.

If controller is properly registered but you still get the white label error page, it likely means one of these:

• You are calling your endpoint with bad url/method/content type
• There is an error happening on your endpoint
• You are not returning proper response (which could cause Spring to show error page)

Which of these cases it is, should be revealed from the produced logs also. Happy hunting!

Custom HTML Error Page using Thymeleaf

Whitelabel error page is default error page generated by Spring Boot when no custom error page is provided.

If you don’t like this default behavior and looking for custom HTML pages to be displayed for different type of HTTP errors then Thymeleaf error templates are simplest approach to follow.

Thymeleaf Error Templates

You create Thymeleaf HTML error template under resources/templates directory:-

1. Generic error template required with name error.html
2. Specific error templates are optional under errors directory with name <error_code>.html for e.g. 404.html for Not found error, 500.html for Internal server error, etc.

Generic Error Template

If specific error template not found then fallback to generic template for all types of HTTP error codes.

resources/templates/error.html

Specific error template 500.html doesn’t exist, display error.html

Specific Error Template

If specific error template found for e.g. 404.html, display it for 404 error!
We imported bootstrap css in the 404 error page to look more elegant.

resources/templates/errors/404.html

Specific error template 400.html exist, display it!

Thymeleaf Dependency

We need to add Thymeleaf dependency in the project for these error templates to work.