Common OJS Errors and How to Fix Them

Diagnose first: where OJS errors are recorded

When people search for "OJS error", they usually see one of a handful of vague messages: a blank white page, "HTTP 500", "A database error has occurred", or a dashboard spinner that never finishes. Those messages only tell you that something failed. Before trying fixes, find out why:

1. Read the error log

   On cPanel hosting, look for an error_log file in the OJS folder, or use the Errors tool in cPanel. On a VPS, check /var/log/apache2/error.log (Debian/Ubuntu), /var/log/httpd/error_log (RHEL-based) or /var/log/nginx/error.log plus your PHP-FPM log. Look for lines containing PHP Fatal error or Uncaught, which name the file and line.

2. Temporarily show errors

   If the log is empty or you have no access to it, turn on debugging in config.inc.php for a few minutes, as shown below. Reproduce the problem, then switch both settings back to Off, because error details reveal server paths to visitors.

3. Clear the caches

   Log in as administrator and use Administration → Clear Data Caches and Clear Template Cache. If you can't log in, delete the contents of cache/t_compile, cache/t_cache, cache/t_config and cache/_db (keep the folders).

4. Check the browser console

   For dashboard problems, open your browser's developer tools and look at the Network tab. A failing /api/v1/… request with status 500 or 403 points to the real error.

[debug]
show_stacktrace = On
display_errors = On

Note your exact version (Administration → System Information) before searching the PKP Community Forum. Fixes often differ between 3.3, 3.4 and 3.5.

OJS email not sending: SMTP, SPF, DKIM and DMARC

Symptoms: new users never get registration or validation emails, reviewers say they never received requests, password resets don't arrive, or messages land in spam folders.

Causes:

• OJS is using PHP mail or sendmail, and the host blocks it or sends it without authentication, so receiving servers treat it as spam.
• SMTP settings are wrong (server, port, encryption or password), or the host blocks outgoing SMTP ports.
• Your domain has no SPF, DKIM or DMARC records.
• OJS sends "from" the editor's personal address (for example a Gmail address). Your server is not allowed to send as that domain, so DMARC checks fail.
• In OJS 3.4 and 3.5, some emails (such as bulk notifications) are sent through the jobs queue. If jobs don't run, these emails wait (see scheduled tasks and jobs).

Fix 1: send through an authenticated SMTP mailbox. Create a mailbox on the journal's own domain, for example journal@yourjournal.org, and configure the [email] section:

[email]
default = smtp
smtp_server = mail.yourjournal.org
smtp_port = 587
smtp_auth = tls
smtp_username = journal@yourjournal.org
smtp_password = "mailbox-password"

; DMARC-friendly sending
allow_envelope_sender = On
default_envelope_sender = journal@yourjournal.org
force_default_envelope_sender = On
force_dmarc_compliant_from = On

In OJS 3.3, the switch is smtp = On instead of default = smtp. The other keys are the same. Use port 587 with smtp_auth = tls, or port 465 with smtp_auth = ssl, whichever your mail provider specifies. Gmail and Microsoft 365 mailboxes often need an app password or extra configuration rather than your normal login password.

Fix 2: make sending DMARC-compliant. With force_dmarc_compliant_from = On, OJS sends every message from your default_envelope_sender address and puts the original sender into Reply-To. Replies still reach the right editor, but receiving servers see a sender your domain authorises. The optional dmarc_compliant_from_displayname setting (for example '%n via %s') shows the editor's name and the journal name.

Fix 3: publish DNS records. Add an SPF record that authorises your mail server, enable DKIM signing in your hosting or mail panel, and add a DMARC record. Then send a password reset to a Gmail address and use Show original to confirm SPF, DKIM and DMARC all show PASS.

OJS upload error: files fail to upload

Symptoms: the upload bar stops or resets, you see "No file uploaded or invalid file type!", or large PDFs fail while small ones work.

Causes and fixes:

• PHP limits too low. Raise upload_max_filesize and post_max_size (post must be at least as large as upload), and for big files also memory_limit and max_execution_time. On cPanel use MultiPHP INI Editor, and on a VPS edit the php.ini used by the web server, then reload PHP.
• Web server limits. Nginx returns 413 Request Entity Too Large unless client_max_body_size is raised. Some Apache hosts set LimitRequestBody.
• Files directory problems. After a migration, files_dir in config.inc.php often still points to the old server's path, or the new folder is not writable by the web server user. Use the absolute path and correct ownership. A full disk or quota produces the same symptom.
• File type detection. OJS checks MIME types with PHP's fileinfo extension. If it is missing, or mime_database_path points to a wrong file, valid files are rejected. Enable fileinfo and comment out mime_database_path.

OJS 500 error and blank white page

Symptoms: a completely white page, "HTTP ERROR 500", or a page that dies halfway, often right after a hosting change, an upgrade or a plugin installation.

Causes and fixes:

• PHP version mismatch. This is the most common cause after a host-wide PHP upgrade. OJS 3.3's README lists PHP 7.3 to 8.2, OJS 3.4 requires PHP 8.0 or newer, and OJS 3.5 requires PHP 8.2 or newer. Select a supported version in cPanel's MultiPHP Manager or your server configuration.
• Missing PHP extensions. The log shows "Call to undefined function", for example mb_…, xml_parser_create or gd functions. Enable the extension (mbstring, xml, intl, gd, zip, curl, fileinfo and so on). See the OJS system requirements for the full list.
• Memory exhausted. "Allowed memory size … exhausted" means raising memory_limit. 256M is a common starting point for OJS.
• Cache not writable. If cache/ or cache/t_compile can't be written, templates can't compile and you get blank pages. Fix ownership and permissions.
• A broken plugin or theme. If the error names a file under plugins/, move that plugin's folder out temporarily and clear the cache.
• Incomplete code. OJS installed from a source-code checkout instead of the release package has no vendor/ libraries. Always install from the official .tar.gz release.
• OJS 3.5: missing app key. 3.5 requires an app_key in [general]. If it is missing after an upgrade, generate one with php lib/pkp/tools/appKey.php generate.

OJS database error: connection problems

Symptoms: "A database connection error occurred", "Database connection failed", or "A database error has occurred" on every page.

Causes and fixes:

• Wrong credentials. Check host, username, password and name in the [database] section. On cPanel, database and user names carry the account prefix (cpuser_ojs). If the password contains special characters, wrap it in double quotation marks.
• Host value. Try localhost, or 127.0.0.1 if socket connections fail. After a migration, the database may be on a different host altogether.
• Old driver name. Use driver = mysqli for MySQL/MariaDB. Very old configurations with driver = mysql fail on PHP 7 and newer.
• Server-side problems. The database server is down, the account hit its connection limit, or the disk is full. Your host can confirm these. Crashed tables can be checked with mysqlcheck.
• "Table doesn't exist" after a move. The dump was imported into a different database than the one configured, or the import stopped partway.

If the error appears only on certain pages, turn on show_stacktrace briefly. A specific SQL error often points to a failed or partial upgrade, which needs careful repair from a backup.

404 errors and clean URL problems

Symptoms: the homepage loads, but article, issue or login pages return 404, or every page shows "No input file specified".

• Clean URLs without rewriting. restful_urls = On removes index.php from links, but only works if Apache mod_rewrite is enabled, the OJS .htaccess rewrite rules exist and the virtual host allows overrides. Fix the server or set it back to Off. The .htaccess example is in our OJS installation guide.
• Nginx without PATH_INFO. OJS URLs like /index.php/journal/article/view/12 rely on PATH_INFO. Your PHP location block needs fastcgi_split_path_info. See the Nginx configuration example.
• Wrong base_url or journal path. After moving to a new domain or folder, update base_url. If someone changed the journal's path in Hosted Journals, old links break unless you add redirects.

Mixed content and redirect loops after switching to HTTPS

Symptoms: the site loads without styling, the browser warns about "not fully secure" content, or you get "too many redirects".

• base_url still uses http. Set base_url = "https://…" under [general] (and any per-journal base_url[path] overrides), then clear the caches.
• Hard-coded http links. Images or scripts added to the footer, sidebar blocks or "About" pages with http:// addresses trigger mixed-content warnings. Edit them to use https://.
• force_ssl behind a proxy or CDN. OJS decides whether a request is secure from the server's HTTPS variable. If a CDN or load balancer ends HTTPS and talks to your server over plain HTTP, force_ssl = On keeps redirecting, forming a loop. Use end-to-end HTTPS (for example a "Full (strict)" CDN mode with a certificate on the origin). Otherwise configure the web server to set HTTPS=on for requests the trusted proxy marks as HTTPS.

Login and session problems

Symptoms: users are logged out immediately or every few clicks, the login form just reloads, or someone is told the account is disabled or not validated.

• Changing IP addresses. session_check_ip = On (the default) ends a session when the user's IP changes. That is common on mobile networks and institutional proxies, and behind a CDN that doesn't pass the real visitor IP. Set it to Off, or configure trust_x_forwarded_for correctly if you run behind a proxy you control.
• Mixed hostnames. If the site works on both www and non-www, or on both http and https, cookies set on one don't apply to the other. Redirect all traffic to the exact base_url host.
• Page caching. A CDN or caching plugin that caches HTML pages can serve stale forms and sessions. Exclude OJS pages from full-page caching.
• Disabled or unvalidated accounts. With require_validation = On, new accounts stay disabled until the validation link is clicked. A journal manager can enable an account under Users & Roles → Users. If many accounts are fake, see stopping OJS spam registrations.

OJS cron not working: scheduled tasks and jobs

Symptoms: review reminders never go out, usage statistics stop updating, DOIs stay "unregistered" despite automatic deposit, or 3.4+ emails are delayed until someone visits the site.

How tasks run differs by version, so check which applies to you (and the README or docs/ folder of your release):

# OJS 3.3 / 3.4 - hourly scheduled tasks
0 * * * * /usr/bin/php /home/cpuser/public_html/tools/runScheduledTasks.php

# OJS 3.5 - scheduler every minute
* * * * * cd /var/www/ojs && /usr/bin/php lib/pkp/tools/scheduler.php run >> /dev/null 2>&1

# OJS 3.4 / 3.5 - process queued jobs (then set job_runner = Off)
* * * * * cd /var/www/ojs && /usr/bin/php lib/pkp/tools/jobs.php run >> /dev/null 2>&1

Common causes:

• The cron uses a different PHP version than the website. On cPanel the default php command may be older. Use the full path of the right version, for example /opt/cpanel/ea-php82/root/usr/bin/php, and confirm it with your host.
• The cron runs as root and creates cache files the web server can't overwrite. Run it as the site's user.
• 3.3/3.4 only: scheduled_tasks is still Off.
• Built-in runners on a quiet site. They only run when someone visits, so a quiet journal processes tasks late. A real cron job is more reliable.

Task logs are stored in scheduledTaskLogs inside your files directory. In 3.4 and 3.5, Administration → Jobs shows queued jobs.

OJS Plugin Gallery not working

Symptoms: Settings → Website → Plugins → Plugin Gallery is empty, keeps loading or shows an error, or installing a plugin fails.

• Outbound HTTPS blocked. The gallery downloads its plugin list from https://pkp.sfu.ca/ojs/xml/plugins.xml. Test from the server with curl -I https://pkp.sfu.ca/ojs/xml/plugins.xml. If that fails, ask your host to allow outgoing HTTPS connections.
• Proxy required. Servers on university networks often need a proxy. Set http_proxy and https_proxy in the [proxy] section.
• Old CA certificates, OpenSSL or a missing curl extension cause SSL errors in the log. Update the server packages or ask your host.
• Install fails. Installing from the gallery or via Upload A New Plugin needs the web server to write to plugins/. Alternatively, extract a plugin release that matches your OJS version into the right plugins/ subfolder, then run php lib/pkp/tools/installPluginVersion.php plugins/generic/pluginname/version.xml.

Our guide to essential OJS plugins explains which plugins are worth installing.

Slow OJS site

• Background work on page requests. PKP recommends moving jobs and scheduled tasks to cron or a worker on busy sites instead of the built-in runners.
• PHP and caching. Use a current PHP 8 version with OPcache enabled. Keep enable_minified = On.
• Aggressive crawlers and bots. Check access logs. Many slow journals are being hammered by bots, and rate limiting or blocking at the server or CDN helps.
• Under-sized hosting. Busy multi-journal installations outgrow basic shared hosting. A database that has grown large needs adequate RAM and tuned MySQL/MariaDB settings.

Quick-reference table: common OJS errors

Still stuck after checking the log? OJS Academy has 10+ years of experience troubleshooting OJS on shared hosting, VPS and university servers. Send us the error and your version through our OJS technical support page, and we will find the cause and fix it properly.

Frequently Asked Questions