Fixing OJS HTTP 500 Internal Server Errors & White Screen of Death
Detailed diagnostic guide for resolving HTTP 500 Internal Server Errors and the White Screen of Death in OJS. Learn how to locate error logs, clear Smarty caches, and resolve fatal PHP crashes.
Real Problem
OJS suppresses detailed error messages in production by default, leaving journal managers staring at a completely blank screen with zero indication of what caused the failure.
Practical Solution
Inspect web server error logs, enable temporary verbose debugging in config.inc.php, clear corrupted compiled template caches in cache/t_compile, and resolve PHP version incompatibilities.
The Psychology and Reality of the White Screen of Death (WSOD)
To an editor or author, a blank white screen looks like total system annihilation. In reality, the "White Screen of Death" is simply PHP’s standard behavior when an unhandled fatal exception occurs while display_errors is disabled in configuration.
PHP halts execution immediately, the web server closes the connection, and an HTTP 500 Internal Server Error status code is returned with an empty response payload.
Step 1: Locating the Hidden Error Log
The answers to 99% of all OJS HTTP 500 errors reside in the server log files. Run the following command in your terminal while refreshing the broken page:
For Nginx + PHP-FPM:
tail -f /var/log/nginx/error.log /var/log/php8.1-fpm.log
For Apache:
tail -f /var/log/apache2/error.log
Look for lines prefixed with:
PHP Fatal error: ... or PHP Parse error: ...
Step 2: Activating Safe Verbose Debugging
If server logs are inaccessible, open config.inc.php and locate the [debug] section:
[debug]
display_errors = On
show_stacktrace = On
Refresh the broken page in your web browser. Instead of a blank page, you will see a detailed backtrace outlining:
1. The exact exception class.
2. The failing file path.
3. The specific line number where execution terminated.
4. The call stack leading up to the failure.
Step 3: The Most Common Root Causes and Fixes
Scenario A: Corrupted Smarty Template Cache
Symptoms: Fatal error in cache/t_compile/*.php.
Fix: Smarty compiled templates can become corrupted after system updates or permission shifts.
Run:
rm -rf /var/www/ojs/cache/t_compile/*
rm -rf /var/www/ojs/cache/*.php
chown -R www-data:www-data /var/www/ojs/cache
Scenario B: PHP Incompatibility (e.g., Running OJS 3.3 on PHP 8.2)
Symptoms: Fatal error: Creation of dynamic property ... is deprecated.
Fix: Downgrade or switch the PHP-FPM pool back to PHP 8.1:
update-alternatives --config php
systemctl restart php8.1-fpm
Scenario C: Database Authentication Failure
Symptoms: PDOException: SQLSTATE[HY000] [2002] Connection refused.
Fix: Verify that MariaDB is running (systemctl status mariadb) and check the password in config.inc.php.
Remember to set display_errors = Off once the root cause is resolved.
Step-by-Step Action Plan
Check Web Server & PHP-FPM Error Logs
Review /var/log/nginx/error.log or /var/log/apache2/error.log for the exact PHP Fatal Error message.
Enable Debugging in config.inc.php
Temporarily set display_errors = On and show_stacktrace = On to view the error directly in the browser.
Clear Compiled Smarty Template Cache
Delete all compiled template files in cache/t_compile/ to resolve template compilation corruption.
Verify PHP Version Compatibility
Confirm that your active PHP runtime matches your installed OJS version requirements.
Check Database Connection Credentials
Verify database host, username, password, and driver in config.inc.php.
Questions People Usually Ask
Why does OJS display a completely blank page instead of an error message?
For security reasons, production installations have display_errors = Off in php.ini and config.inc.php to prevent exposing database credentials and server paths to unauthorized visitors.
What causes the "Allowed memory size exhausted" fatal error in OJS?
This occurs when generating large XML exports, rendering extensive submission grids, or processing high-resolution issue covers. Increase memory_limit = 256M or 512M in php.ini.
How do I clear the OJS cache from the command line when locked out of the admin panel?
Navigate to the OJS root directory and run rm -rf cache/t_compile/* and rm -rf cache/*.php. This forces OJS to recompile all Smarty templates on the next request.
Journal Stuck on a Blank Screen or 500 Error?
AcademiaTech restores crashed OJS platforms immediately, identifying root-cause exceptions and returning your journal to operational health.