Handle Error Codes and Exceptions in web.xml

Important: Do not expose detailed error messages or stack traces to end users. Follow security best practices for error handling. Refer to OWASP Improper Error Handling for guidance.

You can configure error handling for your site application in the web.xml file by defining error-page elements. These elements specify how the application should respond to specific HTTP error codes or Java exception types. A typical configuration at the end of your web.xml might look like the following:

<error-page>
  <error-code>401</error-code>
  <location>/WEB-INF/jsp/errorpages/ErrorPage401.jsp</location>
</error-page>
<error-page>
  <error-code>403</error-code>
  <location>/WEB-INF/jsp/errorpages/ErrorPage403.jsp</location>
</error-page>
<error-page>
  <error-code>404</error-code>
  <location>/WEB-INF/jsp/errorpages/ErrorPage404.jsp</location>
</error-page>
<error-page>
  <error-code>500</error-code>
  <location>/WEB-INF/jsp/errorpages/ErrorPage500.jsp</location>
</error-page>

Note: Tomcat handles HTTP 400 (Bad Request) errors directly and does not forward them to the web application. You do not need to configure an error page for 400 errors in web.xml.

When to Use web.xml Error Pages

Not all errors should be handled through web.xml. For example, it is preferable to handle 404 (Page Not Found) errors using a catch-all sitemap item within the HST request processing pipeline.

Use web.xml error pages as a fallback mechanism. This is relevant when the HST framework cannot process the request, such as when it sends a HttpServletResponse.SC_SERVICE_UNAVAILABLE (503) status code. In these cases, the request is outside the scope of HST processing, and HST-specific features are unavailable. For example, when rendering errorPage500.jsp, the HstRequestContext is already disposed and cannot be accessed.

In contrast, error pages handled by the HST (such as those triggered by a catch-all sitemap item) are processed within an active HST request context. This allows you to use HST features and access the live HstRequestContext object.

404 Handling and Sitemap Items

If a URL does not match any sitemap item, the system throws a org.hippoecm.hst.core.container.ContainerNotFoundException. This exception propagates to the web container, which then applies the <error-code>404</error-code> configuration from web.xml. However, it is recommended to define a catch-all sitemap item to handle unmatched URLs. This approach allows you to generate a user-friendly 404 page and, if desired, suggest alternative content based on the requested URL.

Limitations of JSP Error Pages

JSP error pages defined in web.xml cannot access HST-specific logic. For example, you cannot use <hst:link> tags or other HST tag libraries. This means you cannot generate environment-specific links (such as different CSS paths for local development and production) as you would within HST-managed pages.

Setting the HTTP Status Code in JSP

Some exceptions may not set the correct HTTP status code by default. In these cases, you must explicitly set the status code in your JSP error page using response.setStatus(...).

Example errorPage404.jsp:

<%@ page language="java" contentType="text/html; charset=UTF-8"
    pageEncoding="UTF-8" isErrorPage="true" %>

<% response.setStatus(404); %>

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
 "http://www.w3.org/TR/html4/loose.dtd">
<html>
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
    <title>404 error</title>
  </head>
  <body>
    Page not found!!!
  </body>
</html>

This approach ensures that the correct HTTP status code is returned to the client, even if the exception does not set it automatically.