Diagnosing and Resolving the Drupal White Screen of Death (WSOD)

The Problem: The Silent 500 Error

The "White Screen of Death" (WSOD) occurs when Drupal encounters a PHP fatal error that halts execution before the page can be rendered. Because Drupal's default production settings suppress error messages to protect sensitive system data, the browser displays a blank page or a generic "500 Internal Server Error." The goal is to force the system to reveal the specific PHP exception or memory failure causing the crash.

Quick Diagnostic Matrix

Symptom	Likely Cause	Primary Diagnostic Tool
Blank page on specific content types	PHP Fatal Error in a hook or template	PHP Error Log / Watchdog
Blank page during module update	Incompatible contrib module or missing dependency	Drush / Composer logs
Intermittent blank pages on heavy loads	PHP memory_limit exhaustion	System RAM / php.ini
Blank page after cache clear	Corrupt cache bin or registry issue	drush cr output

Step-by-Step Recovery Process

1. Reveal the Hidden Error

Since the browser is silent, you must check the server-side logs. Access your server via SSH and check the PHP error log. The location varies by OS, but common paths include /var/log/apache2/error.log or /var/log/nginx/error.log.

If logs are empty, temporarily enable error reporting in settings.php. Warning: Do not leave these settings active on a production site.

// Add to settings.php for temporary debugging
$config['system.logging']['error_level'] = 'verbose';
ini_set('display_errors', TRUE);
ini_set('display_startup_errors', TRUE);

2. Analyze the Error Type

Look for entries starting with PHP Fatal error:. The log will provide a file path and line number. Use this to categorize the fix:

• "Allowed memory size of X bytes exhausted": The PHP process ran out of RAM.
• "Call to a member function X() on null": A coding error, often in a custom module or a theme hook.
• "Class X not found": A missing dependency or a failed Composer autoload update.

3. Apply the Targeted Fix

Scenario A: Memory Exhaustion

If the log indicates a memory limit error, check your current CLI limit by running this command as the web user:

php -r "echo ini_get('memory_limit');"

If the limit is low (e.g., 128M or 256M), increase it in your php.ini file. For Drupal 9/10, 512M is generally the recommended minimum for administrative tasks.

memory_limit = 512M

Restart your web server (e.g., sudo systemctl restart apache2) for changes to take effect.

Scenario B: Module Conflict or Code Error

If a specific module is identified in the stack trace, disable it using Drush (Drupal Shell) to restore site access. Run this from the project root as a user with permissions to modify the database:

drush pm-uninstall module_name

If the site is too unstable for Drush, you can manually disable the module in the key_value table of the database, though this is a high-risk operation and requires a backup first.

Scenario C: Cache Corruption

If the error occurs immediately after a deployment or update, the cache may be out of sync with the code. Force a rebuild via the CLI:

drush cr

If drush cr also results in a fatal error, the output in the terminal will be more verbose than the browser, pointing you to the exact file causing the crash.

Verification and Rollback

To verify the fix, navigate to the page that previously triggered the WSOD. If the page loads, check the Recent log messages report in the Drupal admin UI (/admin/reports/dblog) to ensure no suppressed warnings remain.

Rollback: If you modified settings.php to enable error reporting, remove those lines immediately after the fix to prevent leaking system paths to public users.

When to Escalate

If the following conditions are met, the issue is likely a server-level failure or core corruption rather than a module error:

• The WSOD persists after disabling all non-core modules.
• The PHP error logs are completely empty despite the 500 error.
• The server returns a 500 error before PHP is even initialized (check web server config files).