Customizing the Magento Error Report and Maintenance Page

In this tutorial, we will expand on the material Kristof already covered a while ago since there are some neat additional options available to us.

If you’ve worked with Magento for any length of time, you will most certainly be familiar with the dreaded “There has been an error processing your request” page. Clearly, the goal is to make sure that this page never appears to our online customers on a live site, but, on occasion it may still show up. For example if you’ve just sent out a newsletter and have an onslaught of visits, if your server runs out of MySQL connections, your visitors will still see this page.

Similarly, Magento provides an easy way to show a maintenance page. All you have to do is create an empty file called maintenance.flag in your Magento document root and your site will be redirected to the built in maintenance page.

This is all well but as part of a professional solution for your clients, we would like to be able to customize these pages so that they are more in line with the design of the site. Luckily, it is very easy to customize these templates. The principle is very similar to customizing a standard Magento skin folders, so, let’s dig into it.

1. Structure of the Error Pages

The error report and maintenance pages are rendered from template located under [MAGENTO_ROOT]/errors. As you can see from the screenshot, the folder contains some php files and a folder called default that reminds us of the way the normal Magento skin folders are structured. You will notice that the skin folder also contains files with the same name as the error root folder. The difference between them is that the files in the error root are just there to route the specific page processing. They include the processor.php file, instantiate the report class and call the appropriate method which in turn will render the actual page template. For example, the 503.php file has these three lines:

require_once 'processor.php';

$processor = new Error_Processor();

The actual page HTML will be in the phtml files under the default skin folder.

So let’s examine the various files of interest here.

In the error folder:


The good guys from the Magento dev team have provided us with a sample configuration file that we can use to create our specific configuration to customize our error/maintenance pages. We will look into this file in a moment and create our local.xml file once we decide what we want to achieve.


This file is the “engine” that contains all the rendering logic. It implements the Error_Processing class that reads the error template configuration from the local.xml file, loads the configured design and runs the configured design.

404.php, 503.php, report.php

These are the “routing” pages that just invoke the appropriate methods in the Error_Processor class.

The default design folder:


This is the master template file that contains the HTML for all the pages that are handled by the error sub-system. This page will include one of the phtml files listed below. Since this page contains the header and footer you’d clearly want to modify it to implement your own branded design.


This is a 404 Not Found page template. I haven’t seen that one appear on a Magento site since there is already a 404 CMS page built into Magento. However, this page may be useful if you want to change the default 404 handling and direct all 404s to this template. For our purposes, we will ignore this template.


This is the “Temporarily Unavailable” page that also dubs as the maintenance page shown when the site is in maintenance mode. For example, when you are performing upgrades from Magento Connect or manually put the maintenance.flag file up.

We’ll definitely want to customize this page.


This page contains the HTML and PHP code that renders the error report page shown above. It’s certainly another candidate for our customization.

images and css folders

These folders contain the skin CSS and images used by the error/maintenance templates.

2. The local.xml File

Before we dive into customizing the phtml, we should realize that, like with the standard Magento design templates, a similar paradigm is also in effect here. In other words, we don’t want to “hack” the files in the default design, but create our own error design and customize the files there. For this, we will need to create a local.xml file with the appropriate configuration. Opening the supplied sample XML file, we see:

<?xml version="1.0" encoding="UTF-8"?>
            "action" can be set to "print" to show exception on screen and "email"
            to send exception on specified email
            in "subject" you can set subject of email
        <subject>Store Debug Information</subject>
            "email_address" admin email address
            "trash" is handle about trace info
            value "leave" is for store on disk
            value "delete" is for cleaning

The comments in the file are pretty clear but we’ll quickly explain the various elements.

<skin> – this is the element describing which skin folder the error processor should use. So, to create our own skin, we will change “default” to our own custom skin folder, for example:


<action> – is an element that governs what will happen when an error is reported. The values are:

- blank: This is the default value and means that the error report will not be shown on the page but saved in the report file under var/report/

- print: If you want to show the full exception report on the error page, this is the value to use.

- email: You may want the error report page to display an error report form that your customers can fill out when they encounter an error on your site (perhaps to explain the steps they took before the error). This setting will do just that. Note that error report emails will be sent regardless whether the customer fills out the form or not.

The following two elements allow you to set a default email recipient and subject and are relevant only if you set the action to “email” and are self-explanatory. Note that Magento will append the error report number to the subject line automatically.

<trash> is the final element and allows you to specify what you want to happen with the error report files dumped in var/report/. Again, the comments are self-explanatory.

So, we will settle for the following local.xml content:

<?xml version="1.0" encoding="UTF-8"?>
        <subject>XYZ Store Debug Information</subject>
        <email_address>[email protected]</email_address>

In other words, we’ll create a “magebase” skin, we want our customers to be able to submit error reports to us and also leave the report files on the server. If the customer sends a report, our email will have the subject line: “XYZ Store Debug Information [error-number]” and it will be sent to the specified email address (do change that on your own site).

Leave a Reply

Your email address will not be published.

one × 3 =

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>