Custom Error Pages in Liferay DXP

This article shares XTIVIA’s best practice recommendation to handle custom error pages.

Best Practice

The recommended best practice from XTIVIA is to create a static HTML page with corresponding image/css/js assets, which will be stored on the WebServer. A small configuration change at the WebServer level will be required to make this work.
Please note that you can either:

1. Have a custom error page for each error. For example, one custom HTML page for 403s and a completely different page for 404s.
2. Or have one custom error page that will be used for all types of error codes.

Example snippet

The following configuration snippet for Apache HTTPD application shows how to handle custom error pages with an Apache HTTPD WebServer that is forwarding requests to a Liferay application. Please note that the example assumes your error pages are in the “errors” directory under document root.

<VirtualHost *:80>
       ProxyPass /errors !
       ProxyPass / http://localhost:8080/
       ProxypassReverse / http://localhost:8080/
       ProxyErrorOverride On
       ErrorDocument 401 /errors/401.html
       ErrorDocument 402 /errors/402.html
       ErrorDocument 403 /errors/403.html
       ErrorDocument 404 /errors/404.html
       ErrorDocument 500 /errors/500.html
</VirtualHost>

Creating and Using Error Pages in Liferay Application

An alternative approach would be to create custom error pages in Liferay. We do not recommend this approach because of the following considerations:

1. The 404 page and any other error page you use have to be public and cannot be a private page.
2. You cannot use Liferay for any custom 5xx error pages. These must be defined on the WebServer level only; this requires ongoing maintenance at different levels of the infrastructure.
3. If the Liferay instance is down, or if you have performance issues, you won’t be able to use the error pages defined on the Liferay to display the error message to users.

Example snippet

The following configuration snippet for Apache HTTPD application shows how to configure Apache HTTPD WebServer for an error page that is created in Liferay.

<VirtualHost *:80>
       ProxyPass /errors !
       ProxyPass / http://localhost:8080/
       ProxypassReverse / http://localhost:8080/
       ProxyErrorOverride On
       ErrorDocument 404 /web/guest/404-not-found
       ErrorDocument 403 /web/guest/403-access-denied
</VirtualHost>

Summary

A website’s availability and uptime are usually the most important factors from a user experience perspective. However, there are many reasons why things could go wrong – how they are handled is what matters.

With the examples mentioned in this post, you can see that you can take proper steps to provide the right user experience even when things go wrong or when the application is not available due to unforeseen downtime.

If you have questions on how you can best leverage XTIVIA’s experience and/or need help with your Liferay DXP implementation, please engage with us via comments on this blog post, or reach out to us.

Additional Resources

You can also continue to explore Liferay DXP by checking out the following posts.
The Top 10 New Features in Liferay DXP 7 (functional perspective)
How to Set UMASK in Tomcat 8.5
How to Configure Legacy Cookie Processor in Tomcat 8.5 (Application Server configuration perspective)
Top 5 DevOps Features in Liferay DXP (devops perspective)