How to Fix the Spring Boot White Label Error Page (For Real)

Last updated: October 15, 2026

You've built a Spring Boot application. Everything works fine in testing. Then a user stumbles onto a broken link, or the database times out, and they see it: a bland white page with "Whitelabel Error Page" in the corner. No helpful message. No way forward. Just confusion.

That default error page is useful during development, but it has no place in a finished product. Spring Boot makes it straightforward to replace, and you don't need to dig into complex configuration to do it. This guide walks through the options, from simply switching the default off to building a custom error template that gives users the information they actually need.

What happened

• Spring Boot displays its generic white label error page whenever an unhandled exception occurs and no custom page exists
• You can disable it with a single property or by excluding the auto-configuration class
• Custom error pages can live in the public folder or the templates directory, depending on your setup
• Thymeleaf, FreeMarker, and other template engines each have their own convention for error page placement
• For REST APIs, Spring Boot automatically returns JSON instead of HTML when it detects a non-browser client

Why the Default Error Page Falls Short

The white label page exists as a fallback. It has no styling, no branding, and offers only the raw exception message. In a production environment, that's a problem on multiple levels.

Users see something broken with no guidance on what to do next. There's no way to report the issue, no link back to the home page, and nothing that tells them whether the problem is temporary or permanent. From a security standpoint, exposing exception details publicly can leak implementation information that shouldn't leave your infrastructure.

Beyond the user experience issue, the default page makes debugging harder. It works fine when you're running locally and can check console logs, but once your app is deployed, you need error responses that both humans and automated monitoring tools can read.

Your Options for Custom Error Pages

Spring Boot gives you two main paths. The first is to switch the default off entirely and let your servlet container handle errors its own way. That's quick but leaves you with the container's generic page, which isn't much better.

The better approach is to provide your own error page that matches your application's look and feel.

For static HTML files**, place them in `src/main/resources/public/errors/`. A file named `404.html` will automatically display when a page isn't found. This works without any template engine and covers the basics.

For dynamic content**, use your template engine. If you use Thymeleaf, add an `error.html` file to `src/main/resources/templates/`. Spring Boot detects the file and uses it automatically. FreeMarker follows a similar pattern with `error.ftlh`.

With Thymeleaf, you can access `$status` and `$error` variables directly in your template, letting you craft messages like "Page not found" for 404 errors or "Service temporarily unavailable" for 503 responses.

For API-driven clients, Spring Boot already sends JSON when it detects a non-browser request. Your REST endpoints receive structured error data automatically.

Our Analysis

The real question isn't whether to replace the white label page—it's whether you need static or dynamic error handling. Static pages in `public/errors/` are simpler to maintain but can't adapt to different error scenarios. Template-based pages give you flexibility but require a template engine dependency.

Trade-off to consider:** Excluding `ErrorMvcAutoConfiguration` entirely reverts to your servlet container's defaults. This might seem clean, but you lose Spring-specific context entirely. Most teams find it's better to keep the auto-configuration and override the view layer instead.

Who benefits:** End users get a branded, helpful page instead of cryptic error text. Operations teams benefit if you log at the `/error` endpoint before rendering—capturing details server-side while showing only what's appropriate to the user. API consumers are already served by Spring Boot's JSON-first behavior, so your custom HTML pages primarily matter for browser traffic.

What to watch:** If you're building microservices, consider a shared error page template. Consistent error handling across services reduces cognitive load when debugging distributed systems.

What to Watch Next

If you're handling sensitive operations, think about logging before rendering error pages. You can add a controller that intercepts `/error` and records details server-side while still showing a clean page to users. That's the pattern many production applications follow: capture everything, reveal only what's necessary.

The bottom line is straightforward. Don't ship with the default error page. Take thirty minutes to set up a custom template that reflects your application, handles the most common error codes, and gives users a path forward when something goes wrong.

Key takeaways

• Set `server.error.whitelabel.enabled=false` only if you have a replacement ready
• Place static error pages in `public/errors/` or dynamic templates in `templates/` depending on your setup
• Thymeleaf and FreeMarker both support error-specific variables you can use in your templates
• REST clients automatically receive JSON responses, so your custom HTML pages target browser users
• Consider logging at the `/error` endpoint rather than just displaying messages