custom error Jahia 8

How to customize the error pages?

Question

The customer would like to know the how to provide custom error pages in Jahia 8.

Answer

There are several ways to customize error pages, each of them comes with advantages and limitations. The following page covers the different solutions, when and how to apply them.

Providing custom error pages inside Jahia

1 - From a template set (inside a Jahia module): 

The first solution is to package error pages into a templates set module. The source code of the error page will follow your development life cycle and will be easy to deploy. In order to package it into a module, you should add your jsp error files into the folder: /src/main/resources/errors/ 
For instance: /src/main/resources/errors/error_404.jsp
These files need to be included in the module being used to define the template set, thus all sites created with this template set will have these customized error pages.

2 - Community module “Site Settings - Customize error pages”:

It is also possible to use a dedicated module: “Site Settings - Customize error pages”.  This module allows you to designate error pages from the User interface, in admin => sites => “Error page management”. The module does an automatic forward to these error pages in case of error. Note that this is a community module.
You can find the module on Jahia store: https://store.jahia.com/contents/modules-repository/org/jahia/community/site-settings-error-pages.html 

Providing custom error pages outside of Jahia

From Jahia server

If you are using Jahia on premise (hosting Jahia by yourself), it is possible to directly customize the JSP in the Jahia server webapps/ROOT/errors/error_404.jsp. This should be done if this change is global (same 404 error page for all websites.). A restart of Jahia will be needed.

Error Pages filename

Error pages filename match the error it handles. The filename format is error_[http error code].jsp where [http error number] match the http status code. (look at the array below about error pages to provide)

Examples:

error 404 => error_404.jsp
error 500 => error_500.jsp

If the no error page is define, error.jsp is use to display the error. 

Which customized error pages should I provide and where to add them? 

While most error pages will be served by Jahia, you should prepare for the case where Jahia won’t be in a position to respond to the HTTP call (the application server is down, there is a network issue between Apache / Nginx / HAProxy, or else.)
Most of the error pages should also be positioned at the front end server level to account for the situations where Jahia is unavailable. 

Error code Description Should it be customized at the Jahia level? Should it be customized at the Apache / Ngninx / HAProxy
401 Unauthorized
401 should display a page to login to Jahia, more information is available here:
https://academy.jahia.com/training-kb/knowledge-base/override-default-jahia-login-page
Yes No
403 Unauthorized
Should also display login page
Yes No
404 The resource is unavailable Yes Yes
500 The server encountered an unexpected error Yes Yes
501 The server encountered an unexpected error Yes Yes
504 The server timed out Yes Yes