Custom Error Pages with Spring MVC

Refactor Java code safely — and automatically — with OpenRewrite.

Refactoring big codebases by hand is slow, risky, and easy to put off. That’s where OpenRewrite comes in. The open-source framework for large-scale, automated code transformations helps teams modernize safely and consistently.

Each month, the creators and maintainers of OpenRewrite at Moderne run live, hands-on training sessions — one for newcomers and one for experienced users. You’ll see how recipes work, how to apply them across projects, and how to modernize code with confidence.

Join the next session, bring your questions, and learn how to automate the kind of work that usually eats your sprint time.

Distributed systems often come with complex challenges such as service-to-service communication, state management, asynchronous messaging, security, and more.

Dapr (Distributed Application Runtime) provides a set of APIs and building blocks to address these challenges, abstracting away infrastructure so we can focus on business logic.

In this tutorial, we'll focus on Dapr's pub/sub API for message brokering. Using its Spring Boot integration, we'll simplify the creation of a loosely coupled, portable, and easily testable pub/sub messaging system:

>> Flexible Pub/Sub Messaging With Spring Boot and Dapr

1. Overview

A common requirement in any web application is customized error pages.

For instance, suppose you’re running a vanilla Spring MVC app on top of Tomcat. A user enters an invalid URL in his browser and is shown a not so user-friendly blue and white stack trace – not ideal.

In this tutorial, we’ll set up customized error pages for a few HTTP error codes.

The working assumption is that the reader is fairly comfortable working with Spring MVC; if not, this is a great way to start.

This article focuses on Spring MVC. Our article Customize Whitelabel Error Page describes how to create a custom error page in Spring Boot.

2. The Simple Steps

Let’s start with the simple steps we’re going to follow here:

Specify a single URL /errors in web.xml that maps to a method that would handle the error whenever an error is generated
Create a Controller called ErrorController with a mapping /errors
Figure out the HTTP error code at runtime and display a message according to the HTTP error code. For instance, if a 404 error is generated, then the user should see a message like ‘Resource not found’ , whereas for a 500 error, the user should see something on the lines of ‘Sorry! An Internal Server Error was generated at our end’

3. The web.xml

We start by adding the following lines to our web.xml:

<error-page>
    <location>/errors</location>
</error-page>

Note that this feature is only available in Servlet versions greater than 3.0.

Any error generated within an app is associated with a HTTP error code. For example, suppose that a user enters a URL /invalidUrl into the browser, but no such RequestMapping has been defined inside of Spring. Then, a HTTP code of 404 generated by the underlying web server. The lines that we have just added to our web.xml tells Spring to execute the logic written in the method that is mapped to the URL /errors.

A quick side-note here – the corresponding Java Servlet configuration doesn’t unfortunately have an API for setting the error page – so in this case, we actually need the web.xml.

4. The Controller

Moving on, we now create our ErrorController. We create a single unifying method that intercepts the error and displays an error page:

@Controller
public class ErrorController {

    @RequestMapping(value = "errors", method = RequestMethod.GET)
    public ModelAndView renderErrorPage(HttpServletRequest httpRequest) {
        
        ModelAndView errorPage = new ModelAndView("errorPage");
        String errorMsg = "";
        int httpErrorCode = getErrorCode(httpRequest);

        switch (httpErrorCode) {
            case 400: {
                errorMsg = "Http Error Code: 400. Bad Request";
                break;
            }
            case 401: {
                errorMsg = "Http Error Code: 401. Unauthorized";
                break;
            }
            case 404: {
                errorMsg = "Http Error Code: 404. Resource not found";
                break;
            }
            case 500: {
                errorMsg = "Http Error Code: 500. Internal Server Error";
                break;
            }
        }
        errorPage.addObject("errorMsg", errorMsg);
        return errorPage;
    }
    
    private int getErrorCode(HttpServletRequest httpRequest) {
        return (Integer) httpRequest
          .getAttribute("javax.servlet.error.status_code");
    }
}

5. The Front-End

For demonstration purposes, we will be keeping our error page very simple and compact. This page will only contain a message displayed on a white screen. Create a jsp file called errorPage.jsp :

<%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c"%>
<%@ page session="false"%>
<html>
<head>
    <title>Home</title>
</head>
<body>
    <h1>${errorMsg}</h1>
</body>
</html>

6. Testing

We will simulate two of the most common errors that occur within any application: the HTTP 404 error, and HTTP 500 error.

Run the server and head on over to localhost:8080/spring-mvc-xml/invalidUrl.Since this URL doesn’t exist, we expect to see our error page with the message ‘Http Error Code : 404. Resource not found’.

Let’s see what happens when one of handler methods throws a NullPointerException. We add the following method to ErrorController:

@RequestMapping(value = "500Error", method = RequestMethod.GET)
public void throwRuntimeException() {
    throw new NullPointerException("Throwing a null pointer exception");
}

Go over to localhost:8080/spring-mvc-xml/500Error. You should see a white screen with the message ‘Http Error Code : 500. Internal Server Error’.

7. Conclusion

We saw how to set up error pages for different HTTP codes with Spring MVC. We created a single error page where an error message is displayed dynamically according to the HTTP error code.