How to troubleshoot PHP fatal errors with MODX Print

Problem Description

• You've encountered a WSOD or PHP fatal error with MODX
• These appear as a blank white screen, or a 500 HTTP error

Problem Resolution

The blank white screen in a white screen of death (WSOD) or vague error is just the visible output of the actual underlying error. If you do not see a specific error on the screen, this is because your configuration is suppressing the error. This can be a good thing for security, but it does make troubleshooting just a touch more difficult as you’ll need to access your site’s logs to find the error message.

Find the correct error from the logs

Use our guide to learn how to view and identify the correct log entry within Plesk. If you’re using cPanel, you’ll probably have to ask your host to provide the logs.

Once you have associated the white screen of death with the correct error from the logs using the steps described in the above-linked guide, look closely at the error to determine the file path where the problem lies. Here’s an example of a file path you will see in the logs: 

"PHP message: PHP Fatal error: Uncaught DivisionByZeroError: Division by zero in /var/www/vhosts/<domain>/httpdocs/core/cache/includes/elements/modsnippet/95.include.cache.php:243

This means that there is a code snippet with ID 95 where the PHP coding issue lies. You might be able to switch back to an earlier version of PHP to resolve it quickly, but ultimately making this code compatible with newer releases of PHP is your best long-term solution. Below we're going to show how to find the code using that info from the logs, though keep in mind that if you're not familiar with PHP, or coding in general, the specific solution may be something you need to Google to get the right answer.

How to find the responsible code

It may not seem like it, but MODX is actually giving you everything you need to find the source of the issue in the log entry. Using the above entry as reference, follow these steps to find the precise code causing the error:

1. Log in to the site's MODX dashboard/manager
2. In the left column, change tabs from the default "Resources" to "Elements"
3. Scroll down below Templates and Chunks until you find Snippets (we know this is in snippets because the error log entry says 'modsnippet')
4. That very first number (95 in our example) is the ID of the snippet the error lies within. The IDs appear in parentheses to the right of each snippet in MODX, however if you can't find your specific ID, click on any one of them, then in the browser address bar change the ID to the one in the log, such as 95 in our example.
5. In the Snippet Code section on the page, scroll down to the line number where the error occurred - this is found at the end of the log entry and is preceded by a colon. In our example it is line 243.

Once you've found the specific code in question you are where you need to be to resolve the issue! Coding issues that cause fatal errors can be extremely varied, so we can't possibly cover every scenario here, however one really common one at the time of writing is regarding variables not existing because they haven't been defined yet after an upgrade to PHP 8.1. If that sounds like your error, you'll probably need to wrap the code that uses the variable in a conditional like if (exists($variable)){ ...code here... } or define the variable earlier in the code.