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

Troubleshooting

Permissions & File Access​

Configuring File Permissions​

The exact permissions depend on your server's operating system, web server, and PHP setup.

In general, the web server must be able to read and write (recursively) to:

  • files_dir (as set in config.inc.php)
  • cache/
  • public/

The web server should have read-only access to all other files and directories.

mod_php / SAPI​

All PHP scripts run as the same user (usually www-data or nobody). The files_dir, cache/, public/, and their contents must be readable and writable by this user.

chown -R www-data:www-data /var/www/ojs-files
chmod -R 755 /var/www/ojs-files

CGI / FastCGI​

PHP scripts typically run under your own user account. The same directories must be readable and writable by that account.

Linux Permission Examples (Dedicated Hosting)​

PathOwnershipPermissions
cache/, public/, files_dir/apache:www-data750
Other application filesmyuser:www-data640 or 644

For shared hosts, follow your hosting provider's documentation.

note

PHP Safe Mode is not a recommended configuration and may cause mkdir() to create directories that cannot be read or written due to permission conflicts.

HTML Galleys Don't Display Properly​

This is usually caused by the server misidentifying the file type. Check the Galley Edit page β€” if the Label field says "Untitled" instead of "HTML", the file was not correctly identified.

OJS determines file types in this order:

  1. PHP's mime_content_type() function (uses magic.mime)
  2. PHP's finfo_... functions (preferred method)
  3. The external file command: file -bi [filename]

Problems occur if:

  • Your magic.mime file is missing info for the file type.
  • Your server does not support the first two options.
  • You lack permission to run external tools.

Word-processed HTML files often fail to be recognised. Run them through HTML-Tidy to ensure they are valid HTML.

CSS Files Aren't Identified Properly​

This can occur if a CSS file has a comment on the first line. Remove the comment and re-upload.

Also note: do not upload a modified copy of the main OJS stylesheet. Instead, upload a CSS file that only contains overrides for styles you want to change β€” the main stylesheet is applied first.

Character Encoding​

Character encoding issues most commonly occur when migrating journals from another platform or between servers.

Check the current database settings:

SHOW VARIABLES LIKE 'char%';
SHOW VARIABLES LIKE 'collation%';

The goal is to ensure data stored in the database matches the database's character set settings (UTF-8 throughout) and that config.inc.php also uses utf-8 for client_charset, connection_charset, and database_charset.

Common Problem: Latin1 Table Definitions with UTF-8 Data​

If you received a MySQL dump with CHARSET=latin1 table definitions but the data is actually UTF-8:

  1. Request a dump with --default-character-set=latin1: 
    mysqldump db --opt --default-character-set=latin1 --result-file=dump.latin1.sql
  2. In a text editor, remove SET NAMES latin1 from the top.
  3. Replace CHARSET=latin1 with CHARSET=utf8 throughout.
  4. Save as UTF-8 encoding.
  5. Import into a clean UTF-8 database: 
    CREATE DATABASE import_ojs DEFAULT CHARSET utf8;
    USE import_ojs;
    SET NAMES utf8;
    SOURCE dump.utf8.sql;

Common Problem: Smart Quotes from MS Word​

If you see sequences like Ò€œlearning,Ò€, this is caused by copy-pasted Windows-1252 quotes. Use the Python ftfy tool to fix the dump file:

ftfy --output=client.clean.sql client.orig.sql

Before running, add uncurl_quotes=False to the fix_file call in ftfy/cli.py to prevent it from changing the quotes themselves.

Manual SQL Workarounds (Last Resort)​

If you see characters like ΓƒΒ’Γ’β€šΒ¬Γ…", use these SQL replacement commands:

UPDATE article_settings SET setting_value = REPLACE(setting_value, 'ΓƒΒ’Γ’β€šΒ¬Γ…"', '"');
UPDATE article_settings SET setting_value = REPLACE(setting_value, 'ΓƒΒ’Γ’β€šΒ¬ ', '"');
UPDATE article_settings SET setting_value = REPLACE(setting_value, 'ΓƒΒ’Γ’β€šΒ¬Γ’β€žΒ’', '\u2019');

Blank Pages & Error Reporting​

I get a blank page after clicking a button​

  1. Check your web server error log (e.g., /var/log/apache2/error.log). PHP errors are usually logged there.
  2. Check file permissions on cache/ and cache/t_compile.
  3. As a temporary diagnostic, add the following near the top of index.php: 
    ini_set('display_errors', E_ALL);
    Remember to remove this after debugging.

PHP Memory Limit Error​

If you see:

Fatal error: Allowed memory size of NNNN bytes exhausted

Your PHP memory_limit is too low. OJS needs at least 128 MB. Edit php.ini:

memory_limit = 256M

Database Error After Installation​

If you see:

DB Error: Table 'ojs.journals' doesn't exist

The installer could not create the database tables. To fix:

  1. Restore config.inc.php to its template defaults.
  2. Create the database manually via phpMyAdmin or a similar tool.
  3. Restart the installation by loading your OJS root URL.
  4. Fill in the installation form, uncheck Create new Database, and click Manual Install.
  5. Copy the SQL statements and run them against your database manually.

What is a Stack Trace?​

A stack trace shows the code path taken to produce an error. To enable stack traces in OJS, set in config.inc.php:

show_stacktrace = On