So, if you encounter a Magento 2 internal server error, it won’t appear as a white page with black textHave you ever seen a page with “There has been an error processing your request” when using Magento 1 or Magento 2? If no, you are lucky. This page is usually displayed when an issue appears in a system execution flow. Magento processes such issues by creating a separate report file in the var/report directory and by showing the error page with the details. You can also see a similar page “Service Temporarily Unavailable” when the maintenance mode has been enabled. Did you know that you can easily customize these error pages?
We must admit that “Service Temporarily Unavailable” is not a very user-friendly message. So we should put more information on the page, for example the maintenance mode hours.
Error pages in Magento 2 have their own theme. So if you get Magento 2 internal server error, it will look not as a white page with black text. That means we can create a custom theme and use it for error pages. In order to do so, go to the following directory:
pub/errors
You can see a set of default files and local.xml.sample among them. It’s a template for creating a configuration file for the error pages. We need to copy this file and name it as local.xml. The file structure is pretty simple:
<?xml version="1.0"?>
<!--
/**
* Copyright © 2015 Magento. All rights reserved.
* See COPYING.txt for license details.
*/
-->
<config>
<skin>default</skin>
<report>
<!--
"action" can be set to "print" to show exception on screen and "email"
to send exception on specified email
-->
<action>print</action>
<!--
in "subject" you can set subject of email
-->
<subject>Store Debug Information</subject>
<!--
"email_address" admin email address
-->
<email_address></email_address>
<!--
"trash" is handle about trace info
value "leave" is for store on disk
value "delete" is for cleaning
-->
<trash>leave</trash>
</report>
</config>
As shown above, you can configure the current skin. The default theme for error pages is “default”. You can also see a subdirectory named “default” in the same directory. To initialize our own theme we need to create an additional subdirectory – let’s call it “custom”. After creating the subdirectory we can copy the necessary files from pub/errors/default to pub/errors/custom. For example, if it’s a maintenance mode page (actually this page is shown for all errors with code 503), we need to copy pub/errors/default/503.phtml to pub/errors/custom/503.phtml. Now we are able to make our custom changes by editing pub/errors/custom/503.phtml. On the last step, we should switch the error page theme to the newly created one. It can be achieved by changing the skin parameter in pub/errors/local.xml file:
<config>
<skin>custom</skin>
...
</config>
There’s another interesting setting that we can use in the local.xml file. The “action” parameter accepts two values: print and email. As we mentioned before, by default on a critical issue Magento 2 shows “There has been an error processing your request” error page and creates a file with execution flow trace. It’s ok for a production environment but not very handy in development environments. By setting the action value to “print” you will see execution flow trace on the error page itself. By setting the action value to the “email” and editing the rest of the settings you are able to get an email with execution flow trace each time a critical issue appears.
I Hope that you find the information in this post useful. Feel free to leave your proposals and questions in the comments below.
Remember that Atwix offers Magento maintenance services, too.