Whitelabel Error Page in Spring Boot: Fix and SEO Impact

Q: What is the Whitelabel Error Page in Spring Boot?

Spring Boot sends every error to one internal path: /error. The Spring Boot docs explain that it answers in two ways. Apps and API clients get a JSON reply with the status and message. Browsers get a "whitelabel" HTML view. That view is a bare white page. It shows a title, a timestamp, the status code and a short line such as "This application has no explicit mapping for /error, so you are seeing this as a fallback." It has no logo, no menu and no links. Visitors cannot do anything from it except press Back.

Q: How do you test your error pages?

Visit a URL that does not exist, such as /test-missing-page. Run curl -I https://example.com/test-missing-page and check that the first line shows 404, not 200. Throw a test exception on a staging server and check for a 500 status. Check the Page indexing report in Google Search Console for soft 404 warnings. Broken internal links are the most common reason visitors land on an error page at all. Our guide on fixing broken links shows how to find and repair them, and the SEO tools list includes link checkers. A Whitelabel Error Page is not a disaster, but it looks unfinished and helps no one. Replace it with a branded page that sends the right status code, link visitors back to useful pages, and fix the broken links that sent them there.

The Whitelabel Error Page is the plain default error page that Spring Boot shows in a browser when a request fails and your app has no custom error page. It usually appears for a 404 (page not found) or a 500 (server error). You fix it by adding your own error templates or an error controller, and by making sure each error page still sends the correct HTTP status code.

The old version of this article mixed it up with any unbranded 404 page. In practice, "Whitelabel" is a Spring Boot term. If you see that exact title on a site, the site runs on Java with Spring Boot, and the developers have not set up their own error pages yet.

What is the Whitelabel Error Page in Spring Boot?

Spring Boot sends every error to one internal path: /error. The Spring Boot docs explain that it answers in two ways. Apps and API clients get a JSON reply with the status and message. Browsers get a "whitelabel" HTML view.

That view is a bare white page. It shows a title, a timestamp, the status code and a short line such as "This application has no explicit mapping for /error, so you are seeing this as a fallback." It has no logo, no menu and no links. Visitors cannot do anything from it except press Back.

Why does the default error page appear?

The page itself is only a symptom. Something else failed first. These are the common causes:

No controller for the URL. A typo in @GetMapping, a wrong path, or a controller class outside the package that Spring scans gives a 404.
A missing template. A controller returns a view name such as home, but there is no matching file in src/main/resources/templates/.
An uncaught exception. Code throws an error that nothing handles, so the user gets a 500.
A missing static file. A CSS, image or download file was moved or deleted.
A deployment problem. The app starts with the wrong profile or settings, so pages that worked locally fail on the server.

Check your application logs first. The stack trace usually names the exact class or path at fault.

How do you replace it with a custom error page?

Spring Boot gives you several options. Pick the simplest one that fits your app.

Option 1: Static error pages

Add plain HTML files named after the status code. Spring Boot picks them up by name:

src/main/resources/public/error/404.html
src/main/resources/public/error/5xx.html (covers every 500-range error)

Option 2: Template error pages

If you use Thymeleaf or FreeMarker, put templates in src/main/resources/templates/error/, for example 404.html or 5xx.ftlh. Templates can show your normal header, menu and footer. The Spring Boot how-to guide also notes that a single error.html template (Thymeleaf) or error.ftlh (FreeMarker) works as a catch-all.

Option 3: Your own ErrorController

For full control, write a controller that implements ErrorController and handles the /error path. A minimal version looks like this:

Create a class marked @Controller that implements ErrorController.
Add a method with @RequestMapping("/error").
Read the status with request.getAttribute(RequestDispatcher.ERROR_STATUS_CODE).
Return a view such as error/404 or error/500 based on that status.

The package name changed between versions. In Spring Boot 3 the interface lives in org.springframework.boot.web.servlet.error. The Spring Boot 4 docs use org.springframework.boot.webmvc.error. Check the docs for the version you run.

Option 4: Turn the default page off

In Spring Boot 3, set server.error.whitelabel.enabled=false in application.properties. The current Spring Boot 4 docs name it spring.web.error.whitelabel.enabled. The docs warn that this only brings back your server's own default page, such as Tomcat's, so you should add your own page instead of stopping here.

How do error pages affect SEO?

Search engines care less about how an error page looks and more about the status code it sends. Google's documentation on HTTP errors explains the main rules:

4xx codes. Google does not use content from URLs that return 4xx codes. Pages that were indexed drop out over time.
5xx codes. Server errors make Google slow down crawling. Pages already in the index stay for a while, but they drop out if the errors continue.
Soft 404s. If a page looks like an error or is empty but returns 200 (OK), Search Console reports a soft 404.

This is where custom error pages can go wrong. A handmade error controller can easily return a friendly page with a 200 status. Set the status on purpose, for example with ResponseEntity or response.setStatus(404), and test it. Also avoid sending every missing URL to your home page. If a page moved, use a 301 redirect to the new page instead. Our guide to 301 redirects explains when to use one.

What should a good error page include?

Your normal logo, menu and footer, so visitors know they are still on your site.
A short, plain message: "We can't find that page."
Links to your home page, main sections and a search box.
No stack traces or server details. Spring Boot hides the stack trace by default, so keep it that way in production.

How do you test your error pages?

Visit a URL that does not exist, such as /test-missing-page.
Run curl -I https://example.com/test-missing-page and check that the first line shows 404, not 200.
Throw a test exception on a staging server and check for a 500 status.
Check the Page indexing report in Google Search Console for soft 404 warnings.

Broken internal links are the most common reason visitors land on an error page at all. Our guide on fixing broken links shows how to find and repair them, and the SEO tools list includes link checkers.

A Whitelabel Error Page is not a disaster, but it looks unfinished and helps no one. Replace it with a branded page that sends the right status code, link visitors back to useful pages, and fix the broken links that sent them there.

Frequently asked questions

Why do I get a Whitelabel Error Page with status 404?

Spring Boot could not find a controller or static file for that URL. Check the path in your mapping annotation and make sure the controller sits in a package that Spring scans. Then add a custom 404 page.

Does a Whitelabel Error Page hurt SEO?

The status code matters more than the design. A correct 404 or 500 is fine for search engines, though a plain page loses visitors. The real risk is a custom page that returns 200, which Google may flag as a soft 404.

How do I disable the Whitelabel Error Page?

In Spring Boot 3, set server.error.whitelabel.enabled to false. Newer Spring Boot 4 docs use spring.web.error.whitelabel.enabled. It is better to add your own error page, because disabling only shows the server's default page instead.

Whitelabel Error Page: What It Is and How to Fix It