During development or at runtime, errors can occur in Orbeon Forms. There are two main circumstances handled by Orbeon Forms:

• Error page. Errors occurring when producing an entire page on the server. In this case, Orbeon Forms attempts to display an error page.

• Error dialog. Errors occurring in XForms pages when processing Ajax requests. In this case, Orbeon Forms attempts to display an error dialog within the page.

Orbeon Forms provides defaults for the error page and error dialog. The default error dialog looks as follows with Orbeon Forms 3.6:

An initially collapsed section containing details of the error useful to the developer:

Advanced developers can configure the appearance of the error messages. This is discussed in the following sections. In most cases, it is expected that overriding CSS defintions will be enough. Only in more advanced cases should overriding the XSLT stylesheet, XPL pipelines or even reconfiguring the error processors be necessary.

An error occurring during an HTTP request is handled by the error processor associated, in web.xml, with the servlet handling the request. For more information about error processors, please refer to the Packaging and Deployment documentation.

The default error processor is the oxf:pipeline processor, which runs oxf:/config/error.xpl for entire pages, and oxf:/ops/xforms/xforms-server-error.xpl for Ajax requests. These two pipelines are located within orbeon-resources-private.jar.

It is unlikely that you will need to change the configuration of the error processors.

The default error pipeline, oxf:/config/error.xpl, performs the following tasks:

• It uses the oxf:exception processor to serialize Java exception data to XML.

• It formats an error page into an XHTML document using oxf:/config/error.xsl.

• The error page is then procesed by the default theme, oxf:/config/theme-plain.xsl.

• The result is serialized to the client browser with an HTTP status code of 500.

• The client just displays the resulting HTML page.

It is unlikely that you will need to modify this pipeline.

The default Ajax error pipeline, oxf:/ops/xforms/xforms-server-error.xpl, performs the following tasks:

• It uses the oxf:exception processor to serialize Java exception data to XML.

• It formats the error dialog content into an XHTML fragment using oxf:/config/error.xsl.

• The result is converted into serialized HTML embeeded within an XML Ajax response.

• The result is serialized to the client browser, which then displays the content within a dialog.

It is unlikely that you will need to modify this pipeline.

The oxf:/config/error.xsl stylesheet is used to format error pages as well as error dialogs. This stylesheet contains:

• A top-level template displaying an entire error page.

• A template named format-xforms-error-panel-body which formats the error panel message body that appears in the error dialog.

• Named templates, format-message, format-orbeon-call-stack, format-java-stack-trace, and format-message which are shared between the error page and error dialog.

If the default layout of the error page or error dialog does not fit your application, you can change it by overriding this stylesheet under your application's RESOURCES/config/error.xsl.

error.xsl makes use of the error.css stylesheet located under oxf:/config/theme/error.css. If you just want to change the appearance of the error page and/or dialog, you can override these CSS definitions in your application.