Updated on 20/01/2016 for OpenCart 2.x
Even though it's 2016, you may still encounter the dreaded Blank Screen of Death or an Internal Server Error when moving your OpenCart store, installing new modifications or just performing a regular update.
We've revised and updated this post to account for the new version of OpenCart.
This post covers blank pages and internal server errors. If you're struggling with JSON.parse errors in OpenCart, see our other blog post.
First things first – find the actual cause
Although OpenCart is a great shopping cart system, it has its issues – such as the complex upgrade process and often broken releases. It's something we'll need to live with.
It is important to understand, that blank pages and internal server errors don't have a single common cause. Blank pages simply mean something went wrong with your store, therefore it failed to load.
To find out the actual reason for this, you need to look into your server's error log and find the exact error message.
Locate your server's error log
Since the location of the main server error log varies between hosting providers, you'll need to look up the documentation for your particular hosting provider.
In most cases, however, you can also display the contents of the log through your server's administration software (e.g. CPanel).
Enable error logging and display
If you've found the log, but it's empty, you'll need to make sure your errors are getting logged.
To do this, make sure your log is writable and verify the values of the following PHP variables in your php.ini file: display_errors and log_errors.
They are usually set to Off and On in production respectively, but you can change both of them to On for debugging purposes.
If none of this seems to work you can add the following lines of code to the beginning of your index.php file for this debugging session:
error_reporting(E_ALL); ini_set('display_errors', '1'); ini_set('log_errors', '1');
Now when you have the error message, it's time to fix this!
Here are the most common causes of blank pages in OpenCart
Broken OpenCart configuration files
This is a common problem with all OpenCart versions that can happen after you move your store to a different server.
OpenCart stores various pieces of its main configuration in two files: config.php and admin/config.php. If you're moving your store to a different domain or a different server, you may need to adjust some or all of them.
Double check your main store URL in HTTP_ and HTTPS_ variables, paths to your OpenCart setup in DIR_ variables and the database configuration in DB_ variables. All of them should match your new server setup.
Broken directory structure
Although this is a less common cause of blank pages in OpenCart, it is still worth mentioning.
Both admin and catalog folders must follow the same structure in OpenCart:
/catalog/ or /admin/ - controller - language - model - view
You may get a blank page with no errors if this structure is missing the controller/ folder.
Just make sure the folders are in place.
Magic quotes that you forgot to disable
Even though it's 2016 out there, we still see servers with magic quotes enabled once in a while.
This can cause all kinds of issues, including problems resulting in blank pages.
Make sure to disable magic quotes once and for all.
Syntax errors of all kinds
Syntax errors can happen to anyone – an extra bracket, a forgotten comma or a broken extension or vQmod file can easily turn your beautiful store into a blank page.
Fortunately, they're usually easy to fix.
This is what a common syntax error may look like:
[Thu Jan 21 12:48:37 2012] [error] [client 127.0.0.1] PHP Parse error: syntax error, unexpected '}' in /srv/www/dev/opencart/2101/index.php on line 47
Now all you need to do is open up that file and fix that error! Easy.
However, make sure the file name is now one of vQmod's cache files – they usually look somewhat like this: vqmod/vqcache/vq2-catalog_controller_checkout_cart.php. In this case, editing the file directly won't work as it will be overwritten by vQmod.
To fix this, you'll need to find the particular vQmod modification that's causing problems and disable it until you find a way to fix the error.
We suggest searching for the particular piece of code from the error message inside your vqmod/xml/ folder (using Notepad++ file search, for example) and then disabling the broken vQmod file by changing it's extension to .xml_.
This will bring your store back to life while you're writing an angry message to the developer of this particular modification.
Notice: Error: E-Mail to required!
This particular error can be caused by two things – a bug in OpenCart 126.96.36.199 or email missing from your store's configuration.
If you're still using OpenCart 188.8.131.52, you should definitely update to the latest stable version available, otherwise make sure your email settings are correct in Admin > Settings > Your Store > System > Email.
Database errors such as "Table doesn't exist" or "Unknown column in field list"
These errors are almost exclusively caused by third party OpenCart extensions and poorly designed themes.
If you're getting database issues caused by your theme, the number one solution would be to switch to a better OpenCart theme.
Warning: fsockopen(): unable to connect to http://yourdomain.com:25/
This error indicates a problem with either your mail configuration in OpenCart or with your mailserver.
Make sure that your mail settings are correct in Admin > Settings > Your Store > System > Email and that your mailserver is up and running.
These are the most common causes and solutions for blank pages and internal server errors in OpenCart. If we've missed something – tell us in comments below!