Diagnosing the MODX Revolution White Screen of Death and 500 Errors

The condition: a blank page with no clues

You open your MODX Revolution site — or just the Manager — and get a completely white page, or a generic "500 Internal Server Error" with no MODX branding. No error text, no stack trace, nothing in the browser. This almost always means PHP hit a fatal error during the MODX bootstrap, but display_errors is off in your PHP configuration, so the message is written to a log file instead of the screen.

The useful takeaway: a white screen is not a mystery, it is a hidden error message. Your job is to make that message visible, read it, and fix the specific cause. The steps below are ordered from fastest and least invasive to most disruptive, so you can stop as soon as the error reveals itself.

This guide assumes MODX Revolution 2.x or 3.x on a typical LAMP/LEMP stack with PHP 7.4–8.x. Paths assume a standard install; if you moved core/ outside the web root, adjust accordingly.

Likely causes at a glance

Symptom detail	Likely cause	First check
WSOD right after upgrading MODX or PHP	Incompatible extra (plugin/snippet) or PHP version mismatch	PHP error log for a fatal error naming a file in core/components/
WSOD after moving servers or changing paths	Stale absolute paths in cache or config	Manually delete core/cache/ contents
WSOD on both frontend and Manager, nothing changed recently	Database connection failure or disk full	Verify credentials in core/config/config.inc.php; check disk space
500 error only, with web server error page	Web server config issue (bad .htaccess, missing PHP handler)	Web server error log (Apache/nginx), not just PHP log
Intermittent WSOD, sessions dropping	Permissions problem on cache/session directories	Write permissions on core/cache/ and session path

Step 1: Find the real error message

Do not guess. Get the error text first.

Check the PHP error log. Its location depends on your setup — common spots are /var/log/php_errors.log, /var/log/apache2/error_log, or a file named error_log in the site root on shared hosting. Via SSH, run:

tail -n 100 /var/log/apache2/error_log | grep -i "fatal"

Run this as a user with read access to the logs (often root or via sudo). You are looking for lines like PHP Fatal error: ... in /path/to/core/components/someextra/.... The file path in that line is your prime suspect.

If the log is empty or inaccessible, force on-screen errors. Edit core/config/config.inc.php and add or set:

$debug = 1;

In MODX, a $debug value of 1 forces error display. Alternatively, create a small PHP file in the site root:

<?php
ini_set('display_errors', 1);
error_reporting(E_ALL);
require 'index.php';

Load it in the browser to surface the fatal error. Risk: on a production site this can expose absolute server paths and, in some configurations, database credentials to any visitor. Do this briefly, note the error, then revert immediately. Delete the temporary file when done.

Step 2: Match the error to a fix

Fatal error inside core/components/ (an extra)

An extra that worked before an upgrade may call removed MODX classes or use PHP syntax incompatible with your new PHP version. If the Manager is also down, you cannot disable the plugin through the UI. Instead, connect via your database tool and disable it directly:

UPDATE modx_site_plugins SET disabled = 1 WHERE name = 'PluginName';
-- or for snippets:
UPDATE modx_site_snippets SET disabled = 1 WHERE name = 'SnippetName';

Run this against your MODX database with a user that has write privileges (the same credentials from config.inc.php work). Table prefix may differ if you changed it during install. Then clear the cache (Step 3) — MODX caches plugin bindings, so a database change alone may not take effect.

Parse error in config.inc.php

If the log shows Parse error: syntax error pointing at config.inc.php, someone edited it and broke the syntax — usually a missing semicolon or quote. Restore from your last backup or compare against config.core.tpl conventions. Validate before reloading:

php -l core/config/config.inc.php

Run via SSH from the site root. php -l checks syntax without executing the file; expect "No syntax errors detected".

Database connection failure

Confirm the credentials in config.inc.php ($database_user, $database_password, $database_dsn) still work — passwords get rotated and hosts change during migrations. Test from the command line:

mysql -h yourhost -u youruser -p yourdatabase -e "SELECT 1;"

A successful SELECT 1 rules out credentials; a refusal points you to the database layer, not MODX.

Step 3: Clear the cache manually

Corrupted or stale cache — especially after a server move, where absolute paths baked into cached config files no longer exist — is a frequent WSOD cause. Since the Manager is unreachable, clear it by hand. Via SSH from the MODX root:

rm -rf core/cache/*

Or via FTP/SFTP, delete everything inside core/cache/ but keep the directory itself. You need write access to the directory; run as the web server user or your hosting account user, not root, to avoid creating files the web server cannot later overwrite. Caution: the site will rebuild cache on the next request, which makes the first page load slow and can fail if permissions are wrong (Step 4). This changes state, but the cache is regenerable — no rollback needed.

Step 4: Verify permissions

MODX must be able to write to core/cache/ and, depending on setup, session and export directories. A typical fix via SSH:

chown -R www-data:www-data core/cache
chmod -R 775 core/cache

Replace www-data with your actual web server user (nginx, apache, or your account user on shared hosting). On shared hosting without SSH, use your host's file manager to set the cache directory writable. Avoid 777 — it is a common suggestion but unnecessary and insecure on shared servers.

Step 5: Confirm the fix

1. Reload the frontend and /manager/. Both should render.
2. In the Manager, go to Reports > Error Log and confirm no new fatal entries appear after a few page loads.
3. Re-check the PHP error log after browsing several pages — some plugin errors only fire on specific contexts.
4. If you enabled $debug = 1 or a display-errors shim, revert it now and confirm the site still loads with error display off.

When to escalate

• The error log shows fatals inside core/model/modx/ itself, not an extra — this suggests a corrupted core; re-upload the core/ directory from a matching MODX release package.
• The site works after cache clearing but breaks again within hours — suspect a failing disk, an aggressive opcode cache, or a cron job corrupting state; involve your host.
• You suspect a compromised site (unexpected files, modified core). Stop debugging, restore from a known-clean backup, and treat it as a security incident.

Limitations: exact log paths, the $debug behavior, and default table prefixes vary by MODX version and host. Verify against your installation's documentation and your host's control panel before assuming the paths above match yours.