Technical guide on diagnosing the WordPress White Screen of Death. Learn to use WP_DEBUG, interpret PHP error logs, and identify fatal errors on your Hovixa VPS.

Diagnosing the White Screen of Death (WSOD) using WP_DEBUG and error_log

The White Screen of Death (WSOD) is a state where WordPress fails to render any content due to a PHP fatal error. Because production environments are typically configured to suppress error output for security, you are left with a blank browser page. To resolve this on a Hovixa VPS, you must enable the WordPress debug subsystem to expose the stack trace and identify the specific file or plugin causing the crash.

1. Enabling WP_DEBUG in wp-config.php

The most direct way to diagnose a WSOD is to modify your wp-config.php file. By default, debugging is disabled. You should enable it specifically to log errors to a file rather than displaying them to public visitors.

// Locate the line: define( 'WP_DEBUG', false );
// Replace with the following block:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );
    

This configuration ensures that errors are written to /wp-content/debug.log without exposing sensitive server paths to the front-end.

2. Interpreting the Error Log

Once enabled, refresh the white page in your browser. Then, use the terminal to inspect the end of the log file. This is where the "Fatal Error" will be recorded.

# Tail the log in real-time
tail -f wp-content/debug.log
    

Common Fatal Error Types:

• Allowed Memory Size Exhausted: The PHP process hit its limit. Increase memory_limit in php.ini.
• Call to Undefined Function: Typically caused by an inactive plugin or a theme calling a function that doesn't exist.
• Parse Error (Syntax Error): A typo in functions.php or a custom script.

3. Alternative: Checking System PHP Logs

If debug.log remains empty, the error might be occurring before WordPress even initializes. In this case, check the system-level PHP-FPM or Apache/Nginx error logs on your Hovixa VPS.

4. Emergency "Mute" for Plugins

If the log identifies a specific plugin (e.g., /plugins/problem-plugin/index.php) as the source, you can disable it via SSH to restore site access without the admin dashboard.

# Rename the plugin directory to force-deactivate it
mv wp-content/plugins/problem-plugin wp-content/plugins/problem-plugin_old
    

5. Technical Implementation Details

• Security Risk: Never leave WP_DEBUG_DISPLAY set to true on a production site. It can reveal database names, server paths, and version numbers to attackers.
• Log File Permissions: Ensure the web server user (www-data or nobody) has write permissions to the wp-content directory, otherwise debug.log will not be created.
• Memory Limit Edge Case: If the WSOD is caused by a memory limit, the log might show Fatal error: Allowed memory size of X bytes exhausted. Solve this by adding define('WP_MEMORY_LIMIT', '256M'); to your config file.

Sysadmin Tip: If you use a caching layer like **Redis** or **Varnish**, remember to flush your cache after fixing the PHP error. Otherwise, your browser may continue to serve a "cached" white screen even after the underlying code is repaired.