Skip to main content
OJS for Everyone Logo
OJS for EveryoneThe Practical GuidebookRSYN Research LLP

Errors & Troubleshooting

Practical guidance for diagnosing and resolving the most common OJS error conditions.

Why do I get an error when uploading a file?​

File upload failures almost always come down to one of three causes:

1. PHP upload limits are too low

OJS file uploads are bounded by PHP configuration. Check and increase these values in your php.ini:

upload_max_filesize = 20M   ; Maximum size of a single uploaded file
post_max_size = 25M         ; Must be larger than upload_max_filesize
memory_limit = 256M         ; Enough memory to process the file

After editing php.ini, restart your web server for the changes to take effect. On shared hosting, you may be able to override these in .htaccess:

php_value upload_max_filesize 20M
php_value post_max_size 25M

2. The files_dir directory is not writable

OJS saves uploaded files to the directory specified in files_dir in config.inc.php. The web server user must have write permission to this directory. See File Permissions for guidance.

3. Image format issues

If you are uploading images (for journal logos, covers, etc.) and getting errors, ensure you are using PNG or JPEG format. GIF support may be absent depending on how PHP's GD extension was compiled. WEBP support also varies by PHP version.

tip

When reporting an upload error, check the PHP error log (error_log path in your php.ini) for a more specific message — it will usually identify whether the failure is a size limit, a permission error, or something else.

I see strange text like ##navigation.journalHelp## on my site — what does it mean?​

This notation means OJS is looking for a locale translation key that does not exist in the active language files. The text between ## marks is the key name — OJS displays the raw key as a fallback when no translated string is found.

Common causes:

  • A plugin or theme is using a locale key that is not included in its translation file.
  • A custom code modification references a key that was removed or renamed in a newer OJS version.
  • The active language pack is incomplete or outdated.

To fix it:

Use the Custom Locale Plugin (Plugin Gallery) to supply the missing string:

  1. Enable the plugin under Settings → Website → Plugins.
  2. Open the plugin and search for the missing key (e.g. navigation.journalHelp).
  3. Enter your desired text and save.

This is a non-destructive fix that survives upgrades. If the key is missing from the core OJS locale, consider contributing the translation via PKP's Weblate platform so that others benefit from the fix.

info

See the Custom Locale Plugin guide for full instructions on locating and overriding locale keys.

Why do characters appear garbled or strange on my site?​

Garbled characters (often appearing as é instead of é, or boxes instead of special characters) indicate a character encoding mismatch somewhere in the stack.

OJS uses UTF-8 throughout. Check each layer:

LayerWhat to check
DatabaseConfirm the database and all tables use utf8mb4 charset and utf8mb4_unicode_ci collation
PHPEnsure default_charset = "UTF-8" in php.ini
OJS configconnection_charset = utf8 in config.inc.php
HTML outputConfirm the theme template includes <meta charset="UTF-8"> in the page head

The most common culprit is a database table that was created with latin1 encoding, either from an old installation or an import that did not specify UTF-8. Converting a production database's encoding requires careful migration — consult the PKP Admin Guide on character encoding before making changes.

warning

Do not simply change the CHARACTER SET declaration without also converting the data. Changing the charset without re-encoding existing data will corrupt stored content.

How can I prevent spam submissions and fake registrations?​

A multi-layered approach is most effective:

  1. Enable reCAPTCHA — In Administration → Site Settings, configure a Google reCAPTCHA v2 or v3 key. This stops most automated bots at the registration and submission forms.
  2. Moderate registrations — Set Users & Roles → Site Access Options to require Journal Manager approval for new accounts.
  3. Enable email validation — OJS can require users to verify their email address before their account becomes active. This catches disposable-email bots.
  4. Review submission inboxes regularly — Flag and decline obviously spam submissions promptly so they do not accumulate.
  5. Clean up fake accounts — Use the Merge Users tool to merge fake accounts into a dummy target, effectively disabling them while preserving the audit trail.
info

The PKP Admin Guide on Managing Spam provides detailed reCAPTCHA setup instructions and additional hardening recommendations.

A fake journal is impersonating my journal — what can I do?​

Journal hijacking — where a fraudulent site copies a legitimate journal's identity to solicit article processing fees — is a serious and growing problem. If your journal is being impersonated:

  1. Document the evidence — Screenshot the fake site, note the domain name, and record the date you discovered it.
  2. Report to the domain registrar — Use the WHOIS record to find the registrar and file an abuse report, citing trademark infringement or fraud. Many registrars will suspend domains when presented with credible evidence.
  3. Submit a DMCA takedown to Google — If the fake site is appearing in search results, a DMCA removal request to Google can de-index the fraudulent pages.
  4. Notify your readership — Post a clear notice on your journal homepage and send an announcement to all registered users warning them of the fake site.
  5. Report to Retraction Watch — The Hijacked Journals Checker maintains a public list of known hijacked journals. Submit your journal details to be listed, which helps authors avoid the fake site.
  6. Contact your institution — If your journal is affiliated with a university, involve their legal or communications office.
warning

Do not engage directly with the operators of the fake site. Preserve all evidence and route communications through official channels.

How do I interpret OJS error messages?​

OJS error messages typically originate from PHP or the OJS application layer. Here is a quick reference:

Message patternMeaningAction
PHP Deprecated: ...A function used by OJS or a plugin is marked deprecated in your PHP versionUsually harmless; check if an OJS or plugin upgrade is available
xml_parser_create ... not foundPHP xml extension is not installed or not enabledEnable the xml (libxml) extension in your PHP configuration
Permission denied: .../files/...OJS cannot write to the files_dirFix directory ownership and permissions (see Installing & Upgrading)
Parse error: syntax error ...PHP encountered invalid syntax, often because the PHP version is too old for the OJS codeUpgrade PHP to the minimum required version for your OJS release
Call to undefined function ...A required PHP extension is missingIdentify the extension from the function name and enable it
500 Internal Server Error (no detail)PHP fatal error with display_errors offCheck the PHP error log for the actual message

Where to find the PHP error log:

# Common locations
/var/log/apache2/error.log
/var/log/nginx/error.log
/var/log/php_errors.log

# Or check php.ini for the configured path
php -i | grep error_log
tip

During active debugging, temporarily set display_errors = On and error_reporting = E_ALL in php.ini (or in your OJS .htaccess) to see errors inline in the browser. Disable this on production once debugging is complete — detailed error output is a security risk.

Further Reading​