OpenCart 500 error and blank page: what to check

In the admin panel

If the panel opens, look for “Error Logs”: under System → Maintenance in OpenCart 3.0, under System → Tools in 2.1 to 2.3, in the top-level Tools menu in 2.0, and in the System menu in 1.5.

Over FTP or your host’s file manager

The folder is given by the DIR_LOGS line in config.php. The default location depends on the version: 1.5.6 and 2.0.3 use system/logs/; 2.1, 2.2, 2.3 and 3.0 use system/storage/logs/. The file name comes from the “Error Log Filename” setting: error.txt in 1.5.6, error.log in 2.0 and 3.0.

The settings behind the log

Open System → Settings, edit the store and choose the “Server” tab. It holds “Log Errors”, “Display Errors” and “Error Log Filename”. After a standard install the first two are on. Keep “Log Errors” on. “Display Errors” shows errors to visitors, so switch it off on a live shop: the PHP documentation warns that showing errors publicly is a security risk.

When the OpenCart log is empty

OpenCart only logs errors that its own error handler receives. The PHP documentation says such a handler cannot catch the most serious errors, such as E_ERROR and E_PARSE. In that case the PHP or server log may show the cause. Look for “Logs” or “Error log” in your host’s control panel, or ask support to send you the latest errors.

A line from the log tells you which point matters most. Copy a file before you change it, and never edit OpenCart core files without a backup of the whole site and the database.

1. PHP version

If the error appeared without any action from you, check whether your host changed the PHP version. For example, OpenCart 1.5.6 with DB_DRIVER set to mysql calls mysql_* functions, and PHP 7.0 removed that extension. The PHP or server log then shows “Call to undefined function mysql_connect()”. You can go back to an older PHP version if your host’s control panel allows it, or upgrade the shop.

2. File and folder permissions

OpenCart must be able to write to its log and cache folders and, from version 2.0, to its modification and upload folders. They are set in config.php as DIR_LOGS, DIR_CACHE and DIR_DOWNLOAD, plus DIR_MODIFICATION and DIR_UPLOAD from 2.0. Permissions or ownership can change after a move or a restore from a backup. Compare the failing folder with a working one. Do not set 777 on every file; ask your host which permissions are right.

3. The 403 error

According to MDN, 403 means the server understood the request but refuses to fulfil it. After a move or an update, check file permissions and server rules, including .htaccess. The panel message “You do not have permission to modify…” is not a server 403; it is an OpenCart user group permission (System → Users → User Groups).

4. .htaccess and SEO URLs

OpenCart ships a file called .htaccess.txt. For SEO URLs it must be renamed to .htaccess, Apache needs mod_rewrite, and “Use SEO URLs” must be ticked. If the shop sits in a subfolder, set that path in the RewriteBase line.

According to the Apache documentation, a directive that is not allowed in .htaccess, or a syntax error, makes the server return a 500, and the cause goes to the server log. Quick test: copy the file, rename the live .htaccess and check whether the error goes away; SEO URLs will not work in the meantime.

5. PHP memory limit

memory_limit is the most memory one PHP script may use. When it is exceeded, PHP stops and reports “Allowed memory size of … bytes exhausted”. This is a serious error, so look for it in the PHP or server log. Change the limit in your host’s PHP settings or in php.ini. A php_value line in .htaccess only works when PHP runs as an Apache module. Otherwise Apache may not recognise it and return a 500.

6. A recently installed extension or modification

If the error began after installing an extension, suspect it first. OCMOD modifications (from OpenCart 2.0) are managed under Extensions → Modifications. After you enable, disable or delete one, click Refresh, because OpenCart uses modified copies of files that it creates and keeps in the DIR_MODIFICATION folder. Some extensions use vQmod, a separate tool that is not part of OpenCart. A file path in the log can reveal the extension.

7. The storage folder and paths

Both config.php and admin/config.php store folder paths. In OpenCart 3.0 DIR_STORAGE defaults to system/storage/, and the admin panel offers to move that folder outside the public web folder, which changes this value. After a move to another folder or host, old paths can point to a folder that no longer exists, and OpenCart cannot write logs or cache.

8. The ZIP extension error

The OpenCart 3.0 installer shows “Warning: ZIP extension needs to be loaded for OpenCart to work!” It means the server’s PHP has no zip extension enabled, so your host has to enable it. “Zip file could not be opened!” during an extension install is a different case: OpenCart 3.0 could not open the uploaded archive.

Contact me if:

• the shop is unavailable to buyers;
• you have no access to the error logs;
• the error began after an OpenCart, PHP or extension update;
• you are not sure it is safe to change a file.

I review the shop for free and write back with what I found and what I suggest. Before I change anything, I make a backup of the site and the database. I do not promise a fix in advance; I will make my suggestion after the check. More on the Fixing website errors and OpenCart developer pages.