Diagnosing the White Screen of Death (WSOD) in Contao CMS

The Problem: Total Page Failure

A "White Screen of Death" (WSOD) or a generic 500 Internal Server Error in Contao occurs when a PHP fatal error happens before the CMS can render its own error handling interface. Because production environments typically disable display_errors for security, the browser receives an empty response, leaving the administrator with no immediate clue as to whether the failure is due to a corrupted cache, a missing PHP extension, or a version mismatch.

Quick Diagnostic Matrix

Symptom	Likely Cause	Primary Diagnostic Tool
Blank page on all URLs	PHP Version Mismatch / Missing Extension	php -v / php -m
Blank page after update/config change	Corrupted Dependency Injection Container	var/cache inspection
Intermittent 500 errors on uploads	Incorrect Directory Permissions	ls -la on files/ and var/
Blank page only in Backend	Plugin/Extension Conflict	var/log system logs

Step-by-Step Recovery Process

1. Reveal the Hidden Error

Before attempting fixes, you must identify the specific PHP exception. If you have SSH access, check the server's global PHP error log (e.g., /var/log/apache2/error.log or /var/log/nginx/error.log). If logs are inaccessible, temporarily enable error reporting in the entry point.

Action: Edit the index.php file in the root directory. Add these lines immediately after the opening <?php tag:

ini_set('display_errors', 1);
error_reporting(E_ALL);

Risk: Never leave these settings active on a production server, as they expose absolute file paths and database usernames to the public.

2. Clear the System Cache

Contao relies heavily on a compiled container in the var/cache directory. If a file is partially written or a configuration change creates a conflict, the system will crash during the bootstrap process.

Action: Run the following command from the project root via CLI (requires permissions of the web server user, e.g., www-data):

php bin/console cache:clear

If the CLI is unavailable, manually delete the contents of the var/cache/ folder via FTP or File Manager. Note: Do not delete the directory itself, only its contents.

3. Validate Environment Requirements

Updating the server's PHP version without updating Contao (or vice versa) often leads to syntax errors in the core or third-party extensions.

• Version Check: Run php -v. Ensure the version matches the requirements of your specific Contao release (e.g., Contao 5.x requires PHP 8.1+).
• Extension Check: Run php -m to verify that gd, intl, and pdo_mysql are loaded. A missing intl extension, for example, will cause a fatal error during the container build.

4. Audit File System Permissions

If the web server cannot write to the var/ or files/ directories, it cannot store session data or compiled templates, resulting in a 500 error.

Action: Ensure the web server user owns the following directories:

# Example for Ubuntu/Debian Apache
chown -R www-data:www-data var/ files/

Verification and Rollback

To verify the fix, clear your browser cache and attempt to load the /backend login page. If the page loads, the issue was likely cache or permission-related.

Rollback: If you modified index.php to display errors, remove those lines immediately after the site is restored to prevent sensitive data leakage.

When to Escalate

If the following conditions persist, the issue is likely a deeper database corruption or a flawed custom extension:

• The var/log directory is empty despite the WSOD.
• The error log shows Maximum execution time exceeded or Allowed memory size exhausted despite increasing memory_limit in php.ini.
• The WSOD occurs only when accessing specific database-driven pages, but the backend remains functional.