What Is a Whitelabel Error Page? A Complete Technical Guide

When building Java-based applications—especially with Spring Boot—developers sometimes run into a plain white screen titled “Whitelabel Error Page.”
It often appears unexpectedly, usually at the worst possible moment, and raises the same question every time: What exactly caused this, and how do I stop it from happening again?

This guide breaks down the meaning of this error page, why it shows up, and how to replace it with proper error handling for production environments.

What Exactly Is a Whitelabel Error Page?

A Whitelabel Error Page is Spring Boot’s fallback HTML page that appears when the application encounters a problem but cannot find a custom error handler.

In simpler terms:

Your app broke, but Spring Boot had no customized error page to show—so it used its built-in placeholder.

This placeholder appears in both typical web routes and REST endpoints if the backend believes the client expects HTML.

Common triggers include:

• Missing controller mappings
• Exceptions thrown during request handling
• Incorrect request routing
• Disabled or missing template engine
• No custom /error handler defined

While the page itself is harmless, it is not ideal for real-world applications or APIs.

Why Does This Error Page Appear?

Below are the most frequent underlying causes:

1. The requested URL has no matching handler

A user accesses something like:

/api/user/profile/get-more-info

but you only implemented routes under /api/user.

Spring Boot responds with its default error page.

2. The application throws an unhandled exception

For example:

• NullPointerException
• Validation failure
• Database connectivity errors

If you have no global exception handler, the default Whitelabel page is served.

3. The client request is interpreted as a browser request

REST clients should specify:

Accept: application/json

If this header is missing, Spring Boot may assume the client wants HTML and return the Whitelabel page instead of JSON.

4. Missing or incomplete web dependencies

If you accidentally remove a dependency such as:

<artifactId>spring-boot-starter-web</artifactId>

Spring’s auto-configuration may fail, triggering fallback behavior.

5. No custom error controller or custom error template

Spring Boot checks for:

/error
/templates/error/
static/error/

If none are found → fallback page.

How to Remove the Whitelabel Error Page

Spring Boot allows several clean solutions depending on the needs of your application.

Solution 1: Disable the Whitelabel Page Completely

Add this to your configuration:

server.error.whitelabel.enabled=false

This will stop Spring Boot from showing the fallback page.

Solution 2: Create Your Own HTML Error Pages

For web applications, add files such as:

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

Spring Boot automatically uses these when matching status codes.

Solution 3: Implement a Custom Error Controller

Ideal for backend APIs wanting clean JSON responses:

@RestController
public class CustomErrorController implements ErrorController {

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

This ensures all errors return structured JSON instead of HTML.

Solution 4: Add Global Exception Handling

Using @RestControllerAdvice:

@RestControllerAdvice
public class ApiExceptionHandler {

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

This prevents unhandled exceptions from falling back to the default page.

Solution 5: Ensure Frontend Routes and Backend Routes Don’t Collide

Single-page apps (React, Vue, Angular) often refresh pages that don’t exist on the backend.
Configuring a proper fallback or proxy helps avoid unexpected Whitelabel responses.

Best Practices for Production

To avoid the default Spring Boot page entirely, follow these guidelines:

• Always define custom error pages for user-facing apps

• Standardize JSON error responses for APIs

• Implement global exception handling

• Validate your request routing rules

• Make sure your frontend sets proper headers

• Keep logging consistent for easier debugging

With these practices, your users—and your logs—will never again be cluttered with Whitelabel surprises.

FAQ

1. Why do I get a Whitelabel Error Page on page refresh in a React/Vue app?

Because the browser requests a route that only exists on the frontend, not the backend. Set up a frontend fallback route or server rewrite rule.

2. How do I switch error responses to JSON instead of HTML?

Disable Whitelabel, add a global exception handler, and provide a custom /error endpoint returning JSON.

3. Can I remove the Whitelabel Error Page entirely?

Yes.
Just add:

server.error.whitelabel.enabled=false

and implement your own error controller or HTML template.

4. Why does my API return the Whitelabel page instead of an error object?

Most likely because the request lacks:

Accept: application/json

Spring Boot assumes the client wants HTML.

5. Do I need a separate page for each error code?

Not required, but recommended for public-facing sites.
For APIs, one unified JSON structure is usually enough.