Spring Boot - Disabling Whitelabel error page

[Updated: Apr 26, 2017, Created: Jan 27, 2017]

Spring boot uses a default 'whitelabel' error page in browser client if encountered a server error. In this tutorial we are going to see the behavior of whitelabel error page and different options to disable it.


Example

Create a controller

@Controller
public class MyController {

  @RequestMapping("/")
  public String handler (Model model) {
      model.addAttribute("msg",
                         "a spring-boot example");
      return "myPage";
  }

  @RequestMapping("/test")
  public  void handler2 () {
     throw new RuntimeException("exception from handler2");
  }
}

Main class

@SpringBootApplication
public class Main extends SpringBootServletInitializer {

  @Override
  protected SpringApplicationBuilder configure (SpringApplicationBuilder builder) {
      return builder.sources(Main.class);
  }

  public static void main (String[] args) {
      SpringApplication.run(Main.class, args);
  }
}

src/main/resources/application.properties

spring.mvc.view.prefix= /WEB-INF/pages/
spring.mvc.view.suffix= .jsp

pom.xml

<project .....>
<modelVersion>4.0.0</modelVersion>

<groupId>com.logicbig.example</groupId>
<artifactId>disable-whitelabel-error-page</artifactId>
<version>1.0-SNAPSHOT</version>
<packaging>war</packaging>

<parent>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-parent</artifactId>
<version>1.4.3.RELEASE</version>
</parent>

<properties>
<java.version>1.8</java.version>
</properties>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-tomcat</artifactId>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>org.apache.tomcat.embed</groupId>
<artifactId>tomcat-embed-jasper</artifactId>
<scope>provided</scope>
</dependency>
</dependencies>

<build>
<finalName>whitelabel-example</finalName>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<version>1.4.3.RELEASE</version>
<executions>
<execution>
<goals>
<goal>repackage</goal>
</goals>
</execution>
</executions>
</plugin>
<plugin>
<groupId>org.apache.tomcat.maven</groupId>
<artifactId>tomcat7-maven-plugin</artifactId>
<version>2.2</version>
<configuration>
<url>http://localhost:8080/manager/text</url>
<username>joe</username>
<password>joe</password>
</configuration>
</plugin>
</plugins>
</build>
</project>

Not that, we have added tomcat7-maven-plugin to deploy war to tomcat server. We will do that later, first let's run it as exploded application:

mvn spring-boot-run

Output

Entering a URL which is not mapped by our controller, will return whitelabel page with 404

At URI /test, where the mapped handler method throws NullPointerException:

The output will be the same if we package and deploy the war to the tomcat server.



Disabling whitelabel

Method 1: Using 'server.error.whitelabel.enabled=false'

/src/main/resources/application.properties

spring.mvc.view.prefix= /WEB-INF/pages/
spring.mvc.view.suffix= .jsp
server.error.whitelabel.enabled=false

output (mvn spring-boot:run)

As seen above the whitelabel page is not used, also the error is not even handled by the tomcat container's default error handling mechanism.

Deploy war to tomcat:

The above method is meant to be used in embedded container only, but let's deploy the war to tomcat server to see the behavior:

Run the locally installed tomcat server instance('<tomcat-home>/bin/startup.bat') and deploy the war (check out how to deploy war using tomcat maven plugin tutorial):

mvn clean tomcat7:deploy

Output:

As seen above the error is due to not finding 'error.jsp' page and the original error is hidden.


Method2: Using exclude = ErrorMvcAutoConfiguration.class

Comment out the property, 'server.error.whitelabel.enabled' in application.properties

spring.mvc.view.prefix= /WEB-INF/pages/
spring.mvc.view.suffix= .jsp
#server.error.whitelabel.enabled=false

Exclude ErrorMvcAutoConfiguration (which auto configures error page and related classes):

@SpringBootApplication(exclude = ErrorMvcAutoConfiguration.class )
public class Main extends SpringBootServletInitializer {

    @Override
    protected SpringApplicationBuilder configure (SpringApplicationBuilder builder) {
        return builder.sources(Main.class);
    }

    public static void main (String[] args) {
        SpringApplication.run(Main.class, args);
    }
}

Output when running in exploded from (mvn spring-boot:run):

Now redeploy the war project in tomcat server:

 mvn clean tomcat7:redeploy

Output:

The error is handled by tomcat container in both cases.



Conclusion:

If we want to disable whitelabel error page to let servlet container handle the error, use method 2:
@SpringBootApplication(exclude = ErrorMvcAutoConfiguration.class)

To disable it when running in embedded container and we don't want to use container based error handling use method 1:
server.error.whitelabel.enabled=false


Example Project

Dependencies and Technologies Used :

  • spring-boot-starter-web 1.4.3.RELEASE: Starter for building web, including RESTful, applications using Spring MVC. Uses Tomcat as the default embedded container.
    Corresponding Spring version: 4.3.5.RELEASE
  • spring-boot-starter-tomcat 1.4.3.RELEASE: Starter for using Tomcat as the embedded servlet container. Default servlet container starter used by spring-boot-starter-web.
    Corresponding Spring version: 4.3.5.RELEASE
  • tomcat-embed-jasper 8.5.6: Core Tomcat implementation.
  • JDK 1.8
  • Maven 3.3.9

Disable Whiltelabel Example Select All Download
  • disable-whitelabel-error-page
    • src
      • main
        • java
          • com
            • logicbig
              • example
        • resources
        • webapp
          • WEB-INF
            • pages

See Also