Bug – Magento 2 Custom Maintenance & Error Pages

This issue affects the Magento 2.1.* custom maintenance & error pages. I came across this particular issue using Magento CE 2.1.4 which is the latest stable release at the time of writing.

What is it

Magento allows you to create customised error and maintenance pages. See below for an example of the standard Magento 2 maintenance Page:


Magento 2 default Maintenance Page

To create custom maintenance & error pages, you start by

1) creating a copy of the default maintenance & error pages pub/errors/default to pub/errors/custom

2) create pub/errors/local.xml and specify in that file which skin to use:

3) Start customising the pages in pub/errors/custom to suit your needs.

However this does not work as intended – Magento does not use your custom skin and reverts back to default.

The following bug was noted on github and has something to do with your Magento’s web server doc root being magento2/pub instead of magento2/.

I.e. if you are running your production environment as recommended by Magento to use magento2/pub as the doc root, the custom maintenance or error pages will not work.

The bug was noted here: https://github.com/magento/magento2/issues/4305

Apparently there is a fix but it has not been committed into the official release yet.


Currently there is an alternative solution if you’re only looking at setting up a custom maintenance page:

  • Custom static maintenance page via Apache / Nginx (Your web server establishes if a certain file exists in your Magento directory and returns a web server 503 response with the corresponding maintenance page).

You can read more about it here:


In the past for Magento 1 websites, I have always used the Web server (nginx) solution with a custom 503 response page. The Magento guide above is spot on in this case.

Leave a Reply

Your email address will not be published.

This site uses Akismet to reduce spam. Learn how your comment data is processed.