Spring Boot - Disabling Whitelabel error page

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>

Note 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.

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