magento-error-pageIn 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.

Note that the Magento version used for this tutorial is 1.5.

1. Structure of the Error Pages

magento-error-folderThe 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>

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).

3. Creating a Custom Skin

That’s easy, just create a new sub-folder under errors/ and copy the files and folders from the errors/default/ skin there. Done!

Of course, if you this won’t show any changes in the design but, the error page would now look like this:


Now, the task is to customize our design.

4. Customizing the Skin

We mentioned above that the main HTML for these pages comes from page.phtml containing the following code:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "">
<html xmlns="" xml:lang="en" lang="en">
<title><?php echo $this->pageTitle?></title>
<base href="<?php echo $this->getSkinUrl()?>" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="description" content="" />
<meta name="keywords" content="" />
<meta name="robots" content="*" />
<link rel="stylesheet" href="css/styles.css" type="text/css" />
<link rel="icon" href="images/favicon.ico" type="image/x-icon" />
<link rel="shortcut icon" href="images/favicon.ico" type="image/x-icon" />
    <div class="wrapper">
        <div class="page">
            <div class="header-container">
                <div class="header">
                    <a href="<?php echo $this->getBaseUrl()?>" title="Magento Commerce" class="logo"><img src="images/logo.gif" alt="Magento Commerce" /></a>
            <div class="main-container">
                <div class="main col1-layout">
                    <?php require_once $contentTemplate; ?>
            <div class="footer-container">
                <div class="footer">
                    <address class="copyright">Magento is a trademark of Magento Inc. Copyright &copy; 2010 Magento Inc.</address>

So, clearly, the first thing we’d want to do is replace the logo image, link title attribute and image alt attribute, as well as the footer text. Then we can move onto the included phtml templates. And work on our CSS. We can also add or replace the images in the images folder if we need some fancy background or other imagery.

We won’t go into details about how to structure your HTML/CSS, we will leave that up to you since it’s standard web development work.

So, after our Magebase error page makeover, our new pages look like this:


Our custom site maintenance page. Note we added contact info so customers can ring.


Our custom error report page allowing customers to send us additional information


We saw how we can easily customize the default Magento maintenance and error pages by configuring the local.xml file, creating a custom skin folder and adjusting the HTML and CSS supplied in the default skin. You can play around with the settings in local.xml to get the configuration you want and add more meaningful content to the pages themselves.

If you want to change the actual default processing that happens in processor.php, then you’d have to extend the Error_Processor class in your own file and include it in the other *.php files. Bear in mind that those changes may be overwritten during an upgrade. Your custom skin, however, would not be affected.

Finally, there doesn’t seem to be an easy way to create language/locale specific error pages but you can create your custom skin templates in your store’s main language.

Originally published on Copyright © 2011 Magebase - All Rights Reserved.

Back Older article Newer article

New theme released

Responsive Magento Theme - Gala Marcos

A truly impressive Magento template for fashion store from Galathemes, Gala Marcos. It amazes visitors by modern and high-fashion look, and also, neat design.

Read more

Our services


Magento Custom Development

Magento is the most powerful eCommerce system offering rich customization possibilities by extensions and modules.

We offer custom extension development performed by our full-time Magento experts to ensure the custom extension developed follow Magento code standard, optimized and pass our quality tests.

Read more


Magento Custom Design

Design and development a custom Magento template for your Magento store. Our designers and developers are specialists in Magento Commerce and have strong experience in Magento projects.

We provide all design in PSD files, template package and sample data. We also help you install the theme on your store if required. We start your project instantly and with highest priority.

Read more

Magento Template Conversion

PSD to Magento Theme Conversion

PSD to Magento Theme Conversion is a leading strength of us. We have an intelligent process and experienced staff, so you will save much time.

We easily convert a store designs in PSD format into a fully functional Magento commerce template. Quick and convenient for you to create an online store based on Magento is through "PSD to Magento Theme Conversion" service. We bring the flexibility, user friendly modules, and the extensions to improve the functionality of Magento.

Read more


Magento Site Development

We update our Magento knowledge everyday. Having an excellent knowledge on Magento design, Magento programming and server optimization, we guarantee your project get done perfectly.

We apply the philosophy of agile project management to ensure your project always performs on the right way, you'll get updates frequently, any changes of scope of project can be informed early to minimize risks, time and cost.

Read more


Magento Server Optimization

We realy provide the best service for you. Among them are optimized for Magento server is very important. Your ecommerce shop will flexibility and agility absolute. Connecting with customers, processing speed, the gentle query and sensitive to the search engine is very easy

Read more