The MODX White Screen of Death

If a snippet, or sometimes a plugin, contains a fatal PHP error, you mayMODX logo end up looking at the MODX white screen of death. It’s usually a completely blank screen, though if you do a “View Source”, you may see the number one at the upper left of the screen — not much help.

In this article, we’ll look at a method that will sometimes tell you what went wrong.

Plugins make this process challenging because they seldom display errors on the screen. They may place an error in the MODX Error Log that you might not see until much later, by which time there may be many copies of the error message.


The White Screen of Death

Seeing this in MODX is pretty frustrating. It happens because the PHP error_reporting level and the display_errors settings are set to hide PHP errors. This is what you want on a production site. The error messages look bad and can give hackers valuable information. When a problem occurs, though, you need to change things temporarily to see what’s happening.

Go to System (Gear Icon) -> System Settings in the MODX Manager, put debug in the search box at the upper right, and press enter.

You may see several settings (Discuss, for example, has a couple of debug settings). The one you want has the key debug. This is the MODX debug setting. Make a note of the value so you can change it back later.

Double-click on the “value” field or right-click on it an select “Update Setting.” Change the value to -1, that should show all PHP errors. Click outside the debug setting and wait for the little red triangle to disappear. Then, clear the MODX cache.

When you visit the page again, you should see a PHP error message that tells you the name of the offending file and the line number of the error, though the line number may be off by a few lines. If the error message shows a file under the core/cache directory, it should end in the word plugin or snippet followed by a number. That number is the ID of the snippet or plugin causing the error.

Don’t forget to change the debug setting back to its original value after you’ve found the problem.



Sometimes, the error message won’t be very helpful because it will point to the MODX index.php file or a controller file. When a file uses include to make use of another PHP file, an error in the included file will show up as an error in the including file.

If you’re working in a localhost install of MODX (e.g., under XAMPP), or you have control of the server, you can get a little more information about the error by enabling XDebug.

Check phpInfo() to find the location of the php.ini file that PHP is using (there may be several). In the current version of XAMPP, it’s xampp/php/php.ini.

Open the php.ini file in a text or code editor. Look for the [XDebug] section. Uncomment these two lines by removing the semicolon at the beginning:

[code language=”html”]
zend_extension = "C:\xampp\php\ext\php_xdebug.dll"

The first line may look different on your platform, but you should be able to find the XDebug extension.

Now, when a PHP fatal error occurs, you may (or may not) see a stack trace showing the series of actions that preceded the error.


For more information on how to use MODX to create a web site, see my web site Bob’s Guides, or
better yet, buy my book: MODX: The Official Guide.

Looking for quality MODX Web Hosting? Look no further than Arvixe Web Hosting!

Tags: , , | Posted under MODX, MODX | RSS 2.0

Author Spotlight

Bob Ray

Bob Ray is the author of MODX: The Official Guide and over 30 MODX add-on components. He hosts Bob's Guides, a source of valuable information for MODX users, and has been very active in the MODX Forums with over 19,000 posts.

Leave a Reply

Your email address will not be published. Required fields are marked *