Maintenance Page Customisations in Magento 2

Maintenance mode in Magento has been a part of the application for many years and is easy to enable/disable by adding and removing a maintenance flag file.

The message that we’ve become accustomed to over the years in regards to maintenance will look something like the below.

Service Temporarily Unavailable

The server is temporarily unable to service your request due to maintenance downtime or capacity problems. Please try again later.

Whilst maintenance mode is not a key area of the website that merchants worry about, when it is needed, there are often times where merchants may ask the page to be customised, whether that be changing the text or adding a company logo.

Maintenance page customisations in Magento 2 can be achieved without editing the core files.

The first step is to make a copy of the pub/errors/default directory and the contents inside which will be used to contain your customisations. For example, the directory could be called pub/errors/customtheme.

Within the pub/errors directory, there should be a local.xml.sample file. Create a copy of this and rename it to local.xml and add the following:

// pub/errors/local.xml

<?xml version="1.0"?>
<config>
    <skin>customtheme</skin>
</config>

Notice that the value between the pair of <skin> nodes should match the name of the directory you created above within pub/errors.

Now you can edit the files within pub/errors/customtheme to suit your needs.

Please note that if your Magento 2’s document root is set to use the pub/ directory, then there is a bug where Magento does not correctly resolve the path to the maintenance customisations. More information can be seen by looking at the Github issue: https://github.com/magento/magento2/issues/4305.

There is a fix for the above that should be released in Magento CE 2.2, so hopefully we won’t have to wait long for it.

Note: This article is based on Magento CE version 2.1.7.