LightNode Logo

Understanding the Whitelabel Error Page: Causes & Solutions

LightNode
By LightNode ·

1. Introduction

If you’ve worked with Java-based web frameworks—especially Spring Boot—you’ve probably seen a sudden white screen with the title “Whitelabel Error Page.”

It usually pops up when your application encounters an error but has no custom error handler or no matching route.

For end users, this page looks unprofessional; for developers, it often means “something wasn’t mapped or wasn’t handled.”
This tutorial explains what it is, why it happens, and how to fix it with clean, reliable solutions.

2. What Is a Whitelabel Error Page?

A Whitelabel Error Page is a framework-provided default HTML error page.
It appears when:

  • The application doesn’t define its own error page
  • A request hits an unmapped route
  • An exception is thrown but not handled
  • A REST API responds with HTML because the client didn’t declare JSON expectations

In Spring Boot, this is the fallback mechanism provided by the built-in ErrorMvcAutoConfiguration.

3. Common Scenarios That Trigger It

Here are the most frequent causes developers encounter:

  • Requesting a non-existing URL
    Example: /api/unknown-endpoint
  • Missing controller or handler mapping
  • Runtime exceptions with no global exception handler
  • Application missing required Web dependencies
  • Client not sending Accept: application/json so backend returns HTML
  • Template engine errors (Thymeleaf / Freemarker render failures)

4. Why You Should Avoid the Default Page

  • It confuses end users
  • It exposes internal error structure
  • It breaks frontend or API clients that expect JSON
  • It makes debugging & logging inconsistent

Any production-level project should replace it with consistent, user-friendly error handling.

5. How to Fix It (Practical Solutions)

5.1 Disable Whitelabel Error Page

Spring Boot allows you to turn it off:

# application.properties
server.error.whitelabel.enabled=false

5.2 Add a Custom Error Page

For websites (non-API projects):

src/main/resources/templates/error/404.html  
src/main/resources/templates/error/500.html

Spring Boot will automatically use them.

5.3 Add a Global Exception Handler

For REST APIs, returning JSON is better:

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(Exception.class)
    public ResponseEntity<Map<String, Object>> handle(Exception ex) {
        Map<String, Object> body = new HashMap<>();
        body.put("message", ex.getMessage());
        body.put("status", HttpStatus.INTERNAL_SERVER_ERROR.value());
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(body);
    }
}

5.4 Define a Custom /error Handler

@RestController
public class CustomErrorController implements ErrorController {

    @RequestMapping("/error")
    public Map<String, Object> handleError(HttpServletResponse response) {
        Map<String, Object> result = new HashMap<>();
        result.put("status", response.getStatus());
        result.put("message", "Custom error response");
        return result;
    }
}

5.5 Ensure Dependency Completeness

Make sure these dependencies exist:

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-web</artifactId>
</dependency>

@RestController
@RequestMapping("/error")
public class JsonErrorController implements ErrorController {

    @GetMapping
    public Map<String, Object> error(HttpServletResponse response) {
        Map<String, Object> map = new HashMap<>();
        map.put("status", response.getStatus());
        map.put("error", "Something went wrong");
        map.put("timestamp", System.currentTimeMillis());
        return map;
    }
}

7. Best Practices

  • Always define a global error handler

  • Prefer JSON for APIs and custom HTML for web pages

  • Make sure front-end routing and back-end routing don't conflict

  • Validate dependencies & Spring Boot version compatibility

  • Use proper request headers (Accept: application/json) in API calls

FAQ

1. Why does the Whitelabel Error Page appear even when the app starts normally?

Because the backend didn’t find a matching route or error handler for a request. The application can run normally while still having missing mappings.

2. I am building a React/Vue SPA. Why does refreshing the page show Whitelabel Error Page?

Because refreshing triggers a direct backend request to paths like /dashboard which Spring doesn’t map. Fix: configure SPA fallback routing or proxy configuration.

3. Can I completely disable the Whitelabel Error Page?

Yes. Add this to application.properties: server.error.whitelabel.enabled=false Then provide your own /error handler.

4. My API expects JSON but I get an HTML Whitelabel Page. Why?

Your request didn’t include Accept: application/json. Spring defaults to HTML if the client does not specify JSON.

Back to the list