How To Disable Or Customize Spring Boot Whitelabel Error Page

In previous article, we have learnt how to make your spring boot application files structure correct to avoid whitelabel error page ( Spring Boot Resolve Whitelabel Error Page Example ). But when your spring boot application has errors in source code, it still show the whitelabel error page, and you can not see the real error message in the page. This article will tell you how to customize the whitelabel error page and display related error data to client user.

1. Disable Whitelabel Error Page.

If you do not like the whitelabel error page, you can disable it with following method.

  1. Add below content in spring boot project src / main / resources / file.
  2. You can also add below content in above file to exclude ErrorMvcAutoConfiguration class.

Now when you run the spring boot application again, you will see below familiar tomcat error page instead of the whitelabel error page. But below error page is not user friendly, so next we will tell you how to customize the error page.

general tomcat 500 error page

2. Customize Spring Boot Application Error Page.

You have two ways to customize the error page in spring boot.

2.1 Create error.html page in src / main / resources / templates folder like below.

spring boot error html page in src main resources templates folder

Then when your spring boot app runs into error, the error.html page will be displayed. below are error.html file content.

<!DOCTYPE html>
        <meta charset="UTF-8">
        <title>Web Site Error Page</title>
        This is web site error page.

2.2 Create more detail custom error page.

Above error html page is too general, if you want to display more detail error information in the error page, please follow below steps.

  1. Create a class that extends org.springframework.boot.web.servlet.error.ErrorController
  2. Override the getErrorPath() method to return the error page url mapping path.
  3. Create a method that will process the /error page url mapping path. You can return either an error page template file name or error data content string using the @ResponseBody annotation.

In below example, the CustomErrorController class extends ErrorController class. It overrides the getErrorPath method, and add a processError method.

It add the @ResponseBody annotation on the processError method when you want to return the error content directly from the processError method. If you want to return specified template error page, just remove the @ResponseBody annotation from the method.

There is also an error-500.html file added in the src / main / resources / templates folder. This error template file will be used in the custom error controller.

create custom error controller class to display detail error information

package com.dev2qa.example.controller;

import java.util.Map;
import javax.servlet.RequestDispatcher;
import javax.servlet.http.HttpServletRequest;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.web.servlet.error.ErrorAttributes;
import org.springframework.boot.web.servlet.error.ErrorController;
import org.springframework.stereotype.Controller;
import org.springframework.util.Assert;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.context.request.WebRequest;

public class CustomErrorController implements ErrorController {

    // ErrorAttributes object is used to save all error attributes value.
    private final ErrorAttributes errorAttributes;

    public CustomErrorController(ErrorAttributes errorAttributes) {
        Assert.notNull(errorAttributes, "ErrorAttributes must not be null");
        this.errorAttributes = errorAttributes;

    /* Return the error page path. */
    public String getErrorPath() {
        return "/error";

    // Handle the /error path invoke.
   /* @ResponseBody annotation will return the error page content instead of the template error page name. */
    public String processError(HttpServletRequest request, WebRequest webRequest) {

        // Get error status code.
        Integer statusCode = (Integer)request.getAttribute(RequestDispatcher.ERROR_STATUS_CODE);

        if(statusCode.intValue() == 500)
            // If you want to return template error page, then remove the @ResponseBody annotation of this method.
            return "error-500.html";
            // Get error message.
            String message = (String)request.getAttribute(RequestDispatcher.ERROR_MESSAGE);

            // Get exception object.
            Exception exception = (Exception)request.getAttribute(RequestDispatcher.ERROR_EXCEPTION);

            // Get error stack trace map object. 
            Map<String, Object> body = errorAttributes.getErrorAttributes(webRequest, true);
            // Extract stack trace string.
            String trace = (String) body.get("trace");

            StringBuffer retBuf = new StringBuffer();

            if(statusCode != null)
                retBuf.append("Status Code : ");

            if(message != null && message.trim().length() > 0)
                retBuf.append("\n\rError Message : ");

            if(trace != null){
                retBuf.append("\n\rStack Trace : ");


            return retBuf.toString();



<!DOCTYPE html>
        <meta charset="UTF-8">
        <title>Web Site Error Page</title>
        This is internal server error page, error status code is 500.

Below is the custom error page that remove @ResponseBody annotation from processError method. Then when server 500 error occurred, it will display the error-500.html file content.

custom server 500 error page

Below is the error page that use @ResponseBody annotation on processError method, then it will display the processError method returned string on the web page. You should remove below if check code in processError method.

if(statusCode.intValue() == 500)
    // If you want to return template error page, then remove the @ResponseBody annotation of this method.
    return "error-500.html";

customize spring boot application error web page

0 0 vote
Article Rating
Notify of

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Inline Feedbacks
View all comments
Would love your thoughts, please comment.x