Error Handling

Section 1.4 of the Pages specification separates two moments, and a third one appears in practice. The table lists them with what each produces and what the specification promises.

Source: Jakarta Pages 4.0 — 1.4 Error Handling

Source: Jakarta Pages 4.0 — 1.10.1 The page Directive

The two mechanisms that can answer a failure are the JSP page directive (errorPage, per page) and the deployment descriptor (<error-page>, per application, by status code or exception type). The diagram shows how Tomcat 11 chooses between them for a request that reaches a JSP. The text of the specification is: if the page defines an error page through the page directive, the error pages of web.xml are not used for that page.

The branch "translation error" goes to web.xml because the errorPage attribute of a page that did not compile does not exist at run time; the example in Translation-Time Errors shows it.

All the examples are files of one WAR, deployed with the context path /g3errors. The Java classes are in the package org.example.bookshelf (imports and the package line are left out of the listings). The JSPs live under WEB-INF/views, so they are reachable only through a servlet forward, and the error pages under WEB-INF/views/errors. The pom.xml is the one from the Getting Started page of this section (Jakarta Servlet 6.1, Pages 4.0 and EL 6.0 with scope provided, JSTL 3.0 in the WAR).

The model is a catalogue whose find method throws a runtime exception for an unknown id, and a listener that puts the catalogue and the logger into application scope.

Source: Jakarta Pages 4.0 — 1.4.2 Request Time Processing Errors

Two attributes of the page directive connect a failing page to the page that reports the failure.

The failing page and the reporting page of the Bookshelf are two files. The first calls a method of the catalogue from EL, so an unknown id throws.

Source: Jakarta Pages 4.0 — 1.10.1 The page Directive (errorPage, isErrorPage)

A normal request renders the book; an unknown id sends the request and the exception to error.jsp, which the next sections write. The status of the response is 500, as the specification prescribes for an error page:

The isErrorPage rule is enforced when the page is translated. A page that is not an error page and prints exception does not compile; Tomcat reports exception cannot be resolved to a variable and the visitor gets the error page of web.xml.

Source: Jakarta Pages 4.0 — Table JSP.1-7, Implicit Objects Available in Error Pages

An error page has four ways to see what went wrong. They are not equivalent, and one of them, the exception variable, is not available in EL at all.

${exception} in EL is empty even on a page with isErrorPage="true": the table 1-7 variable is a scripting variable, and the JSP expression-language resolvers do not know a name exception. On Tomcat 11.0.26 the expression printed nothing, while ${pageContext.exception} printed the exception class. Use pageContext.

The class of the exception is not always the class you threw. When an EL method call throws, Jasper wraps the exception in a org.apache.jasper.el.JspELException whose cause is yours, and a servlet that forwards to the JSP sees that exception rethrown as a jakarta.servlet.ServletException. The error page below prints the chain so that the layers are visible:

A scriptlet that calls catalog.find directly throws BookNotFoundException itself, with no wrapper. Code that wants the original exception walks getCause() until it reaches the application’s own type.

Writing ${exception.class.name} to print the class does not parse on Tomcat 11.0.26: the page fails with a JasperException "Failed to parse the expression". Use the bracket form ${exception['class'].name} or call ${exception.getClass().getName()}; both printed the name in the test. This matters because many error-page examples written for older containers use the dot form.

Source: Jakarta Pages 4.0 API — PageContext.getException()

Source: Jakarta Servlet 6.1 API — RequestDispatcher.ERROR_EXCEPTION

jakarta.servlet.jsp.ErrorData is an immutable bean built from the Servlet error attributes and exposed as pageContext.errorData (PageContext.getErrorData()). It is meaningful only on an error page. Because the properties are plain getters, EL reads them directly, which the specification gives as the reason for the class: ${pageContext.errorData.statusCode}.

The constructor ErrorData(Throwable, int, String, String) is deprecated for removal since 4.0 and replaced by ErrorData(Throwable, int, String, String, String, String) with the method and the query string. Only containers construct ErrorData; application code never calls it.

Source: Jakarta Pages 4.0 API — ErrorData

Source: Jakarta Pages 4.0 — 1.4.3 Using JSPs as Error Pages

An error page is the one page an attacker can trigger on demand, so it follows four rules: show the visitor a short message and a reference number, log the details once on the server, escape everything that came from the request, and never print a stack trace or an exception message. The Bookshelf puts the logging in a small application-scoped object so that it is shared by every error page and testable.

Source: Jakarta Pages 4.0 API — ErrorData (getMethod, getQueryString, getThrowable)

The error page calls it from EL, prints only escaped values, and keeps the diagnostic list short so that the example shows each ErrorData property; a production page shows only the heading and the reference.

Source: Jakarta Standard Tag Library 3.0 — c:out

The visible result for a missing book, and the single log line that accompanied it:

A request such as ?id=%3Cscript%3Ealert(1)%3C/script%3E is a hostile value. getQueryString() returns the raw string and the error page printed it through c:out, so the page contained id=%3Cscript%3E... as inert text. Printing ${pageContext.errorData.queryString} without c:out, or building a link from it, would be a reflected cross-site scripting hole; the same holds for requestURI, which also comes from the request.

The status of a JSP error page is, by default, ${pageContext.errorData.statusCode}; the specification allows the page to set another value, including 200. Do not: a 200 turns an error into a "soft error" that crawlers index and monitoring does not count.

Because the directive path is a forward (not an ERROR dispatch), a filter mapped to <dispatcher>ERROR</dispatcher> does not run for pages that use errorPage, so a filter is the wrong place to log them. A bean called from the error page logs both paths, as long as every error page calls it.

When a page has no errorPage attribute, or the failure is not an exception of a JSP (sendError, a servlet exception, a 404), the deployment descriptor decides. The container matches the failure to an <error-page>; the page given by <location> receives an ERROR dispatch. The Servlet 6.1 rules, summarised:

The Bookshelf declares three entries:

Source: Jakarta Servlet 6.1 — 10.9.2 Error Pages

The locations may be under WEB-INF, which keeps the error pages out of reach of a direct request. The three entries were exercised with curl; the line that explains each result follows the output.

The third result is a pitfall. /book-plain throws the same BookNotFoundException, but the exception reaches the container as a ServletException that wraps the JSP failure. The first pass matches the java.lang.Throwable entry (every exception is a Throwable), so the second, root-cause pass never happens and the specific BookNotFoundException page is not used. Either map the wrapper types the JSP engine produces, give the JSP an errorPage, unwrap in a filter, or let the generic page branch on the cause. A servlet that throws the exception itself (/missing) matches the specific entry, as the second result shows.

An error page reached from web.xml reads the same information. pageContext.errorData works on those pages too, and the request attributes of the Servlet 6.1 error dispatch are visible; the page printed status=500, method=GET, uri=/g3errors/book-plain, servlet=pages and type=class jakarta.servlet.ServletException for the third request. A POST to /book?id=99 printed method: POST, because the request that failed was a POST while the error dispatch itself is always a GET.

Source: Jakarta Servlet 6.1 — 10.9.3 Error Filters

Source: Jakarta Servlet 6.1 API — RequestDispatcher.ERROR_METHOD

The error attributes, the ERROR dispatcher type and the rule that an error page is invoked through a GET are explained with their own listings on the error pages section of Servlet Fundamentals; this page adds only what is specific to JSP.

c:catch (see JSTL Core) catches any Throwable thrown by the actions nested in it and, optionally, stores it in a page-scoped variable. It is the granular alternative: the specification says actions of central importance should not be wrapped, so that their exception reaches the error page, while actions of secondary importance are wrapped so that they never invoke the error-page mechanism. The variable has page scope, is removed if no exception occurred, and without var the exception is swallowed.

Source: Jakarta Standard Tag Library 3.0 — c:catch

With ?id=99 the response is a normal 200 page with the paragraph "That book is not available."; with ?id=1 it prints <h1>Dune</h1>. A first version of the page also put the exception into an HTML comment for the developer; it printed the class name (org.apache.jasper.el.JspELException), the source line of the page and the EL expression to anyone who viewed the page source. Put diagnostics in the log, not in the response. c:catch has two more limits: everything that was already written stays written (the partial output before the failure is not removed unless the buffer is reset), and a swallowed exception is never logged unless the page logs it.

The buffer attribute of the page directive sets the response buffer. Output is held until the buffer fills or the page ends; only until then can the container still replace the response with an error page. After the buffer was flushed the status line and the headers are on the wire. The specification says a later attempt to dispatch an uncaught exception to an error page "may fail".

Source: Jakarta Pages 4.0 — 1.10.1 The page Directive (buffer, autoFlush)

The observed response was HTTP/1.1 200 with Transfer-Encoding: chunked and 7715 bytes: 181 of the 200 rows, flushed in 1 kB chunks, then a second <html> document, the error page, appended after them. The client received a broken page with a success status. The fixes are the default buffer (8 kB or more) for pages with a late failure, computing everything that can fail before the first byte is written (load the data in the servlet, then forward), and never relying on the error page for a page that streams. Setting buffer="none" makes it worse, because every byte is sent at once.

A JSP that does not compile has no running code, so its errorPage cannot apply. The visitor and the log see a org.apache.jasper.JasperException.

On Tomcat 11.0.26 the log says broken.jsp (line: [6], column: [7]) Unterminated [<c:forEach] tag, the status is 500, and the page rendered was the Throwable entry of web.xml (errors/generic.jsp, printing org.apache.jasper.JasperException), not error.jsp. In production, precompile the JSPs at build time so that translation errors show up in the build instead of on the first request; the Jasper configuration page of this section covers precompilation.

Source: Jakarta Pages 4.0 — 1.4.1 Translation Time Processing Errors

An error page is itself a page and can fail. The specification requires the container to detect a self-referencing error page and throw a translation error. The test below points the errorPage of a page at the page itself and makes the page fail.

Tomcat 11.0.26 did not report a translation error. The page compiled and ran; the failure forwarded to itself again and again until the stack overflowed, and the container answered 500 with a ServletException caused by a java.lang.StackOverflowError, which web.xml rendered through the Throwable page. With no exception thrown, a self-referencing page behaves normally (the first version of the test answered 200). So keep error pages trivial: no calls that can throw, no errorPage of their own, and no dependency on the state that failed (a database, the session).

Source: Jakarta Pages 4.0 — 1.4.3 Using JSPs as Error Pages

When no error page matches, Tomcat writes its own HTML report through the ErrorReportValve. For sendError(410, "This book was withdrawn") it printed the status, the type, the message, a description and the server version Apache Tomcat/11.0.26; for an exception it also prints the stack trace unless the valve is configured otherwise. Both pieces are information an attacker uses: the product and version select the exploit, the stack trace shows packages and file names. The valve has two switches (default true) and can also return static files:

Disabling both returns only the status code. The valve belongs to the host, normally declared in conf/server.xml:

Source: Apache Tomcat 11.0 — Error Report Valve

The shared Tomcat of this test could not be reconfigured, so the host-level snippet above was not run. What was run is the temptation to keep the setting in the application: a META-INF/context.xml with the same <Valve> inside <Context>. It changed the report to the bare "HTTP Status 418 – Unknown Reason" as intended, but it also made every <error-page> stop working: the 404 page, the exception pages and the Throwable page were all replaced by the bare status page, because the context-level valve writes the report before the host dispatches to the descriptor’s error pages. Configure the valve at the host, or leave the application’s <error-page> entries to do the work and make sure every status and the Throwable has one, including a default entry.

Older JSP code prints the exception from a scriptlet. This is a "before" snippet kept only to recognise it in legacy code.

With /legacy?id=99 the page answered 500 and printed 3204 bytes: the exception message, the application’s class names and line numbers (Catalog.java:16, legacy_jsp.java:123), and the Jasper and Tomcat internals. The replacement is the page above: the reference id for the visitor, ErrorLog for the operator. A scriptlet that reads exception gets the BookNotFoundException itself, with no JspELException wrapper, because the exception was thrown by the scriptlet code and not by EL.

Source: Jakarta Pages 4.0 — Table JSP.1-7, Implicit Objects Available in Error Pages

Struts 7 does not use errorPage. Action exceptions are handled by exception-mapping elements and the exception interceptor, and validation errors by field and action errors; see Exception Handling and Global Results and Validation in the Struts part of this section. The JSP side of a Struts application is still the same: a JSP result that can fail has the same errorPage, web.xml and escaping rules as above, and the container error pages catch what the framework does not.

Source: Jakarta Pages 4.0 — C.1 Changes between JSP 4.0 and JSP 3.1

Source: Jakarta Servlet 6.1 — Appendix A, Changes Since 6.0

The JSP 1.2 and JSTL 1.0 books cover the same ideas, and the ideas still hold: an errorPage attribute, an isErrorPage attribute, a c:catch for the page-local failure, error pages that collect diagnostics, and pageContext.exception for JSTL pages. What is different today: