Docs Developer Site
Developer Docs Enonic Development Kit next Web HTTP Error handler

HTTP Error handler

Contents

An app may replace XP’s default error page with its own.

Introduction

When a request fails, XP responds with a default error page. In production it shows the status and a short message; in dev mode it also shows the stack trace. Neither is the best way to greet your users, so an app can supply an error handler that renders the response instead.

Error handlers are looked up per request, based on which app was serving it. If no handler produces a response, XP’s default error page is used.

error.ts

An app handles its own errors with the file src/main/resources/error/error.ts. It is used for every request the app serves: webapps, APIs, admin tools and extensions, and site pages, as described below.

Rather than exporting HTTP methods like HTTP functions and filters do, an error handler exports one function per status code it wants to handle, named handle<status>, plus an optional catch-all handleError:

Basic error handler
export function handle404(err) {
    return {
        contentType: 'text/html',
        body: `
<html>
  <body>
      <h1>No page for you!</h1>
  </body>
</html>
`
    };
}

export function handleError(err) {
    return {
        contentType: 'text/html',
        body: `
<html>
  <body>
      <h1>Error code "${err.status}"</h1>
  </body>
</html>
`
    };
}

A handler function returns an HTTP response, or nothing to decline. Declining hands the error on to the next candidate, so an app may choose to handle a 404 itself and leave everything else to the default page. The response keeps the error’s status code unless the handler sets status itself.

Sites

A site request is served by all the apps added to the site, so XP walks them in the site’s app order. For each app it looks for src/main/resources/cms/error/error.ts first, and then for the general error/error.ts. The first handler that returns a response wins.

cms/error/error.ts is therefore an optional override for site pages. An app that serves a site and an API can give site visitors a branded error page from cms/error/error.ts, while its API keeps returning the plain responses from error/error.ts. An app with only error/error.ts uses it for both.

Resolution order

For a failed request, XP tries the following in order and stops at the first response:

  1. handle<status> in the candidate handlers - for a site, in every app in order, cms/ file before general file.

  2. For a 401, the ID provider bound to the request, through its handle401 function.

  3. handleError in the candidate handlers, in the same order as step 1.

  4. XP’s default error page.

Because step 1 covers all apps before step 3 begins, a handle404 in the second app of a site wins over a handleError in the first.

Custom error handlers do not run while a site is rendered in Content Studio’s edit mode, so editors see the underlying error rather than the branded page.

Should an error occur inside an error handler, it is logged and XP falls back to the default error page.

Error handlers should be implemented to execute as fast as possible, and preferably without additional API requests, i.e. fetching content. The reason for this is that the error handler itself may then recursively fail. Also, slow error pages may impact the performance of a node negatively if errors occur frequently. You can choose different handling based on the type of error. A 404 might for instance be handled differently than other errors.

The Error object

The input parameter for handler functions is an error JSON object. The object contains the status code, error message, Exception object, and the original HTTP request object:

Sample error object
{
    "status": 404,
    "message": "Some error message",
    "exception": "<the actual exception object in Java>",
    "request": "<original request JSON>"
}

Contents

Contents