OJS White Screen After Update: Causes and Fixes

The Update Ran. Now Your Journal Is Gone.

You followed the upgrade instructions. You uploaded the new OJS files. You ran the upgrade script. Everything seemed to go smoothly, until you loaded your journal and found a completely blank white page staring back at you.

No error message. No explanation. Just white.

The OJS white screen after update is one of the most alarming situations a journal editor or administrator can face. Your journal was live and accepting submissions minutes ago. Now it looks like it doesn't exist. Authors trying to submit see nothing. Reviewers trying to access their queue see nothing. Your editorial team is locked out.

The white screen, sometimes called the White Screen of Death, is OJS's way of failing silently when a fatal PHP error occurs but error display is turned off. The journal isn't gone. The data isn't lost. But something in the update process went wrong, and OJS can't load enough of itself to tell you what.

This guide covers every known cause of the OJS white screen after an update, how to diagnose the specific problem on your installation, and the exact steps to fix it, written by OJS specialists who have recovered journals from this exact situation hundreds of times.

If your journal is down right now and you need it back up fast, visit ojsguru.com for priority OJS support.

Why OJS Updates Cause White Screens

OJS updates are not simple file replacements. A full OJS upgrade involves three interconnected operations happening at the same time:

File replacement, new PHP, JavaScript, and template files overwrite the old ones. If this is interrupted or incomplete, you end up with a mix of old and new files that are incompatible with each other.

Database migration, OJS runs SQL scripts that alter your database structure to match the new version. If this fails midway, your database schema is partially upgraded, out of sync with both the old and new application files.

Cache invalidation, OJS stores compiled templates and configuration data in its cache directories. After an update, old cached files can conflict with new application code, causing rendering failures.

When any of these three operations fails or is interrupted, due to a PHP timeout, a memory limit, a file permission error, or a server hiccup, the result is almost always the same: a white screen.

The good news is that in almost every case, the data in your database is intact. The journal's articles, users, and submissions are safe. What's broken is the application layer sitting on top of that data.

Step 1: Enable Error Display to Find the Real Problem

A white screen gives you nothing to work with directly. Your first step is always to expose the actual PHP error that OJS is hiding.

Option A, Edit config.inc.php:

Open your OJS config.inc.php file and find:

display_errors = Off

Change it to:

display_errors = On

Reload your journal. Instead of a white screen, you should now see a PHP error message. This message tells you exactly what went wrong and which file caused it.

Option B, Check OJS error log:

/path-to-your-ojs/cache/logs/errors.log

Option C, Check server PHP error log:

On Ubuntu/Debian:

sudo tail -100 /var/log/apache2/error.log

On CentOS/RHEL:

sudo tail -100 /var/log/httpd/error_log

Once you have the actual error message, match it to the causes below. After fixing the problem, set display_errors back to Off, never leave error display on for a live journal.

Cause 1: Incomplete File Upload During Update

The most common cause of a white screen after an OJS update is an incomplete file transfer. If your FTP client timed out, your internet connection dropped, or the upload was interrupted for any reason, some new OJS files never made it to the server, leaving your installation in a mixed state of old and new code.

How to identify this cause:

Your error log shows messages like Failed opening required, No such file or directory, or Class not found referencing specific OJS core files.

How to fix it:

The safest fix is to re-upload the complete OJS package rather than trying to identify and replace individual missing files.

1. Download the correct OJS version package from pkp.sfu.ca
2. Extract it locally
3. Do not overwrite config.inc.php, this contains your database credentials
4. Do not overwrite your public/ directory, this contains uploaded files
5. Re-upload all other files to your server, overwriting existing files
6. Run the OJS upgrade script again if the database migration was also incomplete

Using command line (faster and more reliable than FTP):

# Download OJS package directly to server
wget https://pkp.sfu.ca/ojs/download/ojs-3.3.0-18.tar.gz

# Extract
tar -xzf ojs-3.3.0-18.tar.gz

# Copy files, preserving your config and uploads
cp -r ojs-3.3.0-18/* /path-to-your-ojs/ --exclude=config.inc.php

Cause 2: PHP Memory Limit Exhausted During Upgrade

OJS upgrade scripts are memory-intensive. They process database migrations, rebuild caches, and load large portions of the application simultaneously. On servers with a PHP memory limit below 256MB, the upgrade script runs out of memory before completing, leaving the installation in a broken state.

How to identify this cause:

Your error log shows PHP Fatal error: Allowed memory size of X bytes exhausted or the upgrade appeared to complete but the journal shows a white screen immediately after.

How to fix it:

First, increase PHP memory limits before attempting any further upgrade steps:

On cPanel hosting, edit PHP settings: Go to MultiPHP INI Editor, select your domain, and set:

memory_limit = 256M
max_execution_time = 300
max_input_time = 300

On VPS, edit php.ini directly:

sudo nano /etc/php/8.1/apache2/php.ini

# Update these values
memory_limit = 256M
max_execution_time = 300
max_input_time = 300

sudo systemctl restart apache2

Via .htaccess (shared hosting):

php_value memory_limit 256M
php_value max_execution_time 300

After increasing memory limits, clear the OJS cache and re-run the upgrade script:

# Clear OJS cache
rm -rf /path-to-ojs/cache/fc/*
rm -rf /path-to-ojs/cache/t_cache/*
rm -rf /path-to-ojs/cache/templates_c/*

# Re-run upgrade
php tools/upgrade.php upgrade

Cause 3: Database Migration Failed or Is Incomplete

The white screen after an OJS update frequently points to a database schema mismatch, and the application files expect a database structure that doesn't exist yet because the migration script didn't complete successfully.

How to identify this cause:

Your error log shows messages like Unknown column, Table doesn't exist, SQLSTATE error, or references to specific database tables that OJS is trying to access.

How to fix it:

Step 1, Restore from backup first if available:

If you took a database backup before upgrading (which you always should), restore it now and start the upgrade process fresh with correct PHP memory limits and execution time settings.

# Restore database from backup
mysql -u db_username -p db_name < backup_before_upgrade.sql

Step 2, Re-run the upgrade script:

cd /path-to-your-ojs
php tools/upgrade.php upgrade

Watch the output carefully. If errors appear during the migration, note the specific SQL error and the table name involved.

Step 3, If no backup is available:

This is a more complex recovery situation. Depending on how far the migration progressed, you may need to:

• Manually complete specific database alterations
• Use OJS's database repair tools
• Restore from the most recent available backup even if it's older

This is a situation where professional help is strongly recommended to avoid making the database inconsistency worse.

Cause 4: PHP Version Incompatibility With New OJS Version

Each OJS version has specific PHP version requirements. When you upgrade OJS to a newer version, the new version may require a higher minimum PHP version than what your server is running, causing fatal errors on every page load.

How to identify this cause:

Your error log shows PHP Fatal error, Deprecated, Call to undefined function, or Syntax error messages. The error appeared immediately after the update, not during the upgrade script itself.

OJS PHP version requirements:

How to fix it:

Check your current PHP version:

php -v

If it falls outside the supported range for your new OJS version, update PHP to a compatible version.

On cPanel hosting: Go to MultiPHP Manager, select your domain, and choose the correct PHP version.

On Ubuntu VPS:

# Install correct PHP version (example: PHP 8.1 for OJS 3.3.x)
sudo apt install php8.1 php8.1-mysql php8.1-xml php8.1-mbstring php8.1-intl php8.1-curl php8.1-zip php8.1-gd

# Set as default
sudo update-alternatives --set php /usr/bin/php8.1
sudo systemctl restart apache2

After updating PHP, clear your OJS cache and reload the journal.

Cause 5: Plugin Incompatibility With New OJS Version

Plugins built for an older OJS version may not be compatible with the version you just upgraded to. When OJS loads an incompatible plugin during startup, it can generate a fatal PHP error that prevents any page from rendering, including the admin panel you'd normally use to disable it.

How to identify this cause:

Your error log references a path inside a specific plugin directory, something like /plugins/generic/pluginname/PluginClass.php. The white screen appeared after the upgrade and the log points to plugin code rather than OJS core files.

How to fix it, when you can't access the admin panel:

Method A, Disable via database:

UPDATE plugin_settings 
SET setting_value = '0' 
WHERE setting_name = 'enabled';

This disables all plugins at once. After your journal loads, re-enable them one by one to identify the problematic one.

Method B, Rename plugin directory:

# Disable a specific plugin by renaming its directory
mv /path-to-ojs/plugins/generic/problemplugin \
   /path-to-ojs/plugins/generic/problemplugin_DISABLED

Method C, Move all third-party plugins temporarily:

# Create a temporary holding directory
mkdir /tmp/ojs_plugins_backup

# Move all plugins from the generic directory
mv /path-to-ojs/plugins/generic/* /tmp/ojs_plugins_backup/

After your journal loads, move plugins back one at a time to identify which one is causing the conflict.

Once the incompatible plugin is identified, check the PKP Plugin Gallery for an updated version compatible with your new OJS version.

Cause 6: Old Cached Files Conflicting With New Code

OJS compiles and caches templates, configuration data, and class files to improve performance. After an upgrade, old cached files from the previous OJS version can conflict with the new application code, causing rendering failures that present as a white screen.

How to identify this cause:

The upgrade script completed without errors, PHP version is correct, and no plugin errors appear in the log, but the white screen persists. This is often a cache problem.

How to fix it:

Clear all OJS cache directories completely:

# Clear compiled templates
rm -rf /path-to-ojs/cache/fc/*
rm -rf /path-to-ojs/cache/t_cache/*
rm -rf /path-to-ojs/cache/templates_c/*

# Clear CSS and JS cache
rm -rf /path-to-ojs/cache/css/*
rm -rf /path-to-ojs/cache/_db/*

# Clear the public cache
rm -rf /path-to-ojs/public/fc/*

After clearing cache, reload your journal. OJS will rebuild its cache from scratch using the new application files.

If your hosting environment uses server-level caching (Varnish, Nginx FastCGI cache, Cloudflare), purge those caches as well, they may be serving the white screen page from cache even after OJS itself is fixed.

Cause 7: File Permission Errors After Upload

When new OJS files are uploaded during an update, their ownership or permissions sometimes don't match what the web server requires. Files owned by your FTP user rather than the web server user (typically www-data on Ubuntu) will cause permission denied errors that can produce a white screen.

How to identify this cause:

Your error log shows Permission denied, failed to open stream, or Unable to write to directory. These errors often reference OJS cache directories or the files upload directory.

How to fix it:

# Set correct ownership (replace www-data with your web server user)
sudo chown -R www-data:www-data /path-to-ojs/

# Set correct permissions
sudo find /path-to-ojs/ -type d -exec chmod 755 {} \;
sudo find /path-to-ojs/ -type f -exec chmod 644 {} \;

# Ensure cache and public directories are writable
sudo chmod -R 775 /path-to-ojs/cache/
sudo chmod -R 775 /path-to-ojs/public/

# Protect config file
sudo chmod 600 /path-to-ojs/config.inc.php

After fixing permissions, clear the cache and reload your journal.

Cause 8: config.inc.php Was Overwritten During Update

If the OJS update process overwrote your config.inc.php file, either accidentally during a file upload or because the upgrade instructions weren't followed carefully, your database credentials and site configuration are gone. OJS can't connect to the database and returns a white screen on every page.

How to identify this cause:

Your error log shows Access denied, No such database, or Connection refused errors. Or your config.inc.php file now contains template placeholder values instead of your actual database credentials.

How to fix it:

If you have a backup of config.inc.php:

# Restore config from backup
cp /path-to-backup/config.inc.php /path-to-ojs/config.inc.php

If you don't have a backup:

You'll need to manually re-enter your database credentials into config.inc.php. Copy the template from your OJS installation:

cp /path-to-ojs/config.TEMPLATE.inc.php /path-to-ojs/config.inc.php

Then edit it with your database details:

[database]
driver = mysqli
host = localhost
username = your_db_username
password = your_db_password
name = your_db_name

[general]
base_url = https://yourjournal.com
files_dir = /path-to-your-files-directory

This is why backing up config.inc.php before any upgrade is essential, it takes 10 seconds and can save hours of recovery work.

Cause 9: Upgrade Script Not Run After File Update

Some editors upload new OJS files but don't run the upgrade script that migrates the database to match the new version. The new application code expects a database structure that the old database doesn't have, resulting in a white screen on every page.

How to identify this cause:

Your error log shows Unknown column, Table doesn't exist, or similar database errors. You updated files via FTP but didn't run the upgrade script.

How to fix it:

Run the OJS upgrade script from your server command line:

cd /path-to-your-ojs
php tools/upgrade.php upgrade

If you don't have SSH access, OJS also provides a web-based upgrade tool. Navigate to:

https://yourjournal.com/index.php/index/install/upgrade

Follow the on-screen steps. After the upgrade script completes successfully, reload your journal.

Quick Diagnostic Checklist

Work through this in order before attempting any fix:

• Enable display_errors = On in config.inc.php and reload, what error appears?
• Check OJS error log at /cache/logs/errors.log
• Check server PHP error log
• Verify all OJS files uploaded completely, with no FTP interruptions
• Check PHP version is compatible with new OJS version
• Check PHP memory limit is at least 256M
• Verify upgrade script was run after file upload
• Check for plugin errors in log, disable all plugins and retest
• Clear all OJS cache directories
• Verify config.inc.php still contains correct database credentials
• Check file permissions, cache and public directories must be writable

How to Safely Run OJS Updates, Preventing White Screens Before They Happen

The best way to deal with an OJS white screen after update is to never get one in the first place. These practices eliminate the vast majority of update-related failures:

Always back up before updating, with no exceptions. Take a complete backup of your database and your entire OJS files directory before touching anything. A backup from 10 minutes before the upgrade is the difference between a 5-minute recovery and a 5-hour ordeal.

# Database backup
mysqldump -u db_user -p db_name > ojs_backup_$(date +%Y%m%d).sql

# Files backup
tar -czf ojs_files_backup_$(date +%Y%m%d).tar.gz /path-to-ojs/

Test the upgrade on a staging server first. Clone your live OJS installation to a staging environment, an identical copy on a separate server or subdomain. Run the full upgrade there. Confirm everything works before touching your live journal. This single practice eliminates almost all upgrade-related emergencies.

Increase PHP limits before upgrading. Set memory_limit = 256M and max_execution_time = 300 before running any OJS upgrade script. Reset them after if needed.

Read the OJS release notes before upgrading. Every OJS release includes upgrade notes that flag PHP version requirements, plugin compatibility changes, and known issues. Spending 10 minutes reading them can prevent hours of recovery work.

Never upgrade directly from OJS 2 to the latest OJS 3. Major version jumps require intermediate steps. Skipping them corrupts the database migration and almost always produces a white screen or worse. Follow the documented upgrade path from PKP.

Clear cache immediately after every upgrade. Even when an upgrade appears to succeed, always clear OJS cache directories as the final step. Stale cache is one of the easiest problems to prevent.

When to Call in a Professional

Recovering from an OJS white screen after update is manageable if you have server access, a recent backup, and time to work through the diagnosis methodically.

But there are situations where professional help is the faster, safer choice:

• Your journal has no pre-upgrade backup and the database migration failed midway
• The white screen appeared on a live journal mid-review-cycle with active submissions
• You don't have SSH access to run upgrade scripts or check error logs
• Multiple fixes have been attempted and the white screen persists
• Your error log references database corruption or missing core tables

Attempting further fixes in these situations without expert guidance risks compounding the problem, especially if database integrity is already compromised.

OJS Guru recovers OJS installations from failed upgrades and white screen errors as a priority service. Send us your journal URL and a description of what happened, and we'll diagnose and fix it, typically within one business day.

👉 Get a free consultation at ojsguru.com

Summary

The OJS white screen after update is alarming, but it is always caused by something specific and recoverable. The nine causes covered in this guide account for the vast majority of post-update white screens in production:

1. Incomplete file upload during update
2. PHP memory limit exhausted during upgrade
3. Database migration failed or is incomplete
4. PHP version incompatibility with new OJS version
5. Plugin incompatibility with new OJS version
6. Old cached files conflicting with new code
7. File permission errors after upload
8. config.inc.php overwritten during update
9. Upgrade script not run after file update

Enable error display, check your logs, work through the diagnostic checklist, and apply the relevant fix. In most cases, especially when a backup exists, your journal will be back online within the hour.

If the upgrade went wrong and you need expert recovery help, especially without a backup, contact OJS Guru at ojsguru.com. We've recovered journals from far worse situations and we can recover yours too.

OJS Guru is a professional Open Journal Systems service provider specializing in OJS installation, customization, migration, and technical support for research journal publishers in 20+ countries. Visit ojsguru.com to request a free consultation.