Proper Method to Remove Whitelabel Error Page in Spring Boot

Problem Background Analysis

During Spring Boot application development, many developers encounter the need to customize error pages. By default, Spring Boot provides a "Whitelabel" error page, which often appears unprofessional in production environments. However, when attempting to remove or replace this default page, developers frequently face mapping conflict issues.

Common Error Scenarios

Many developers first attempt to directly map the /error path in a Controller:

@RestController
public class IndexController {

    @RequestMapping(value = "/error")
    public String error() {
        return "Error handling";
    }

}

This approach causes Spring Boot to throw a BeanCreationException, with specific error messages indicating ambiguous mapping:

Exception in thread "AWT-EventQueue-0" org.springframework.beans.factory.BeanCreationException: 
Error creating bean with name 'requestMappingHandlerMapping': 
Invocation of init method failed; 
nested exception is java.lang.IllegalStateException: 
Ambiguous mapping found. Cannot map 'basicErrorController' bean method 
to {[/error],methods=[],params=[],headers=[],consumes=[],produces=[],custom=[]}: 
There is already 'indexController' bean method

Root Cause Analysis

The fundamental cause of this issue lies in Spring Boot's auto-configuration mechanism. When no explicit implementation of the ErrorController interface is present, Spring Boot automatically registers BasicErrorController as the default error handling Bean. This auto-registered Bean already occupies the /error path mapping, causing conflicts with developer-defined Controllers.

Correct Solution

To properly remove the Whitelabel error page and implement custom error handling, the ErrorController interface must be implemented:

@RestController
public class IndexController implements ErrorController{

    private static final String PATH = "/error";

    @RequestMapping(value = PATH)
    public String error() {
        return "Error handling";
    }

    @Override
    public String getErrorPath() {
        return PATH;
    }
}

Implementation Principle Details

By implementing the ErrorController interface, Spring Boot's auto-configuration mechanism recognizes this custom implementation and consequently does not automatically register BasicErrorController. This avoids mapping conflicts while ensuring error requests are correctly routed to custom handling logic.

Configuration Property Settings

Beyond code-level implementation, error handling behavior can be further controlled through configuration files. Add to application.properties:

server.error.whitelabel.enabled=false

This setting completely disables the Whitelabel error page, but it's important to note that setting this property alone without providing custom error handling implementation may result in the application container's (e.g., Tomcat) default error page being displayed.

Advanced Configuration Options

For more complex scenarios, auto-configuration exclusion can be considered:

spring.autoconfigure.exclude=org.springframework.boot.autoconfigure.web.servlet.error.ErrorMvcAutoConfiguration

Or using annotations on the main configuration class:

@EnableAutoConfiguration(exclude = {ErrorMvcAutoConfiguration.class})

Custom Error Page Enhancement

In practical applications, more comprehensive error handling functionality is often required. Status code-specific error pages can be implemented by extending error handling methods:

@RequestMapping("/error")
public String handleError(HttpServletRequest request) {
    Object status = request.getAttribute(RequestDispatcher.ERROR_STATUS_CODE);
    if (status != null) {
        Integer statusCode = Integer.valueOf(status.toString());
        if(statusCode == HttpStatus.NOT_FOUND.value()) {
            return "error-404";
        }
        else if(statusCode == HttpStatus.INTERNAL_SERVER_ERROR.value()) {
            return "error-500";
        }
    }
    return "error";
}

Best Practice Recommendations

In actual project development, the following best practices are recommended:

• Always implement the ErrorController interface to avoid mapping conflicts
• Explicitly set server.error.whitelabel.enabled=false in application.properties
• Provide specific error pages for different HTTP status codes
• Add appropriate logging in error handling methods
• Ensure custom error pages feature good user experience design

Conclusion

By correctly implementing the ErrorController interface, developers can effectively remove Spring Boot's default Whitelabel error page and provide customized error handling solutions that meet application requirements. This approach not only resolves mapping conflict issues but also provides a solid foundation for further error handling extensions.