Diagnosing the White Screen of Death (WSOD) in ProcessWire

The Problem: Silent Failures

A "White Screen of Death" (WSOD) or a generic 500 Internal Server Error occurs when ProcessWire encounters a fatal PHP error before the page can be rendered. Because ProcessWire suppresses errors by default to protect sensitive server paths from public view, the browser receives an empty response, leaving the administrator with no immediate clue as to whether the failure is due to a syntax error, a memory leak, or a database disconnect.

Quick Diagnostic Reference

Symptom	Likely Cause	Primary Diagnostic Tool
Blank page immediately after module install	PHP Version Mismatch / Fatal Error	/site/config.php debug mode
Blank page on specific page loads	Template Syntax Error / Memory Limit	PHP Error Log (error_log)
500 Error across entire site	.htaccess or Permission Issue	Server Access Logs
Blank page after server migration	Database Connection Failure	db.php verification

Step 1: Force Error Visibility

The first priority is to move the error from the server log to the browser. This should only be done in a development environment or during a brief maintenance window, as it exposes system paths.

1. Open /site/config.php using an FTP client or SSH.
2. Locate the configuration section and add or modify the following line:

   $debug = true;

3. Refresh the page. If the error is a PHP Fatal or Parse error, the specific file and line number will now appear on the screen.

Step 2: Analyzing the Error Type

Depending on the output from Step 1, apply the corresponding fix:

Parse Error or Fatal Error

These usually occur in /site/templates/ or within a third-party module. If the error points to a specific module file, the module may be incompatible with your current PHP version.

• Fix: If you cannot access the admin panel, manually rename the offending module folder in /site/modules/ (e.g., rename MyModule to MyModule_disabled). ProcessWire will ignore the module, potentially restoring site access.

Allowed Memory Size Exhausted

This happens when a template loop is too large or a complex database query exceeds the PHP memory_limit.

• Fix: Increase the limit in your php.ini or .htaccess file. For example, in .htaccess:

  php_value memory_limit 256M

• Risk: On shared hosting, setting this too high may cause the host to kill the process automatically.

Database Connection Failure

If the screen remains white even with $debug = true, the failure may be occurring during the database handshake in /site/config.php.

• Check: Create a file named test_db.php in your root directory with the following content (replacing placeholders with values from your config):

  <?php
  $conn = new mysqli('DB_HOST', 'DB_USER', 'DB_PASS');
  if ($conn->connect_error) {
      die('Connection failed: ' . $conn->connect_error);
  } 
  echo 'Connected successfully';
  ?>

• Action: Run this file via the browser. If it fails, verify your database credentials and ensure the database server is accepting connections from your web server.

Step 3: Verifying File Permissions

ProcessWire requires specific permissions to execute PHP and write to the assets folder. Incorrect permissions can trigger a 500 error before PHP even executes the config.php.

• Check: Ensure /site/assets/ is writable by the web server user (typically www-data or apache).
• Command (Linux/SSH): Run the following as a user with sudo privileges to ensure the web server owns the assets directory:

  sudo chown -R www-data:www-data /var/www/html/site/assets/

Verification and Rollback

Once the site is accessible, verify the fix by navigating to the specific page that triggered the WSOD. Check the /site/assets/logs/ (if configured) to ensure no secondary warnings are being generated.

Rollback: To return the site to a secure state, you must remove the debug flag from /site/config.php:

// Remove or comment out this line
// $debug = true;

Escalation Criteria

If the following conditions persist, the issue is likely at the server/OS level rather than the CMS:

• The test_db.php script connects successfully, but index.php still returns a 500 error.
• The PHP error log is completely empty despite a blank page.
• The issue persists after renaming all custom modules and templates.

In these cases, contact your systems administrator to check the Apache/Nginx error logs for segmentation faults or security module (e.g., ModSecurity) blocks.