Troubleshooting Blank Pages and Oops Error Message
In this article we describe what to do when one of our modules displays blank pages or errors. Before contacting technical support, please read this article where we address the most common causes of "Oops" or empty pages.
First thing first, we need to get error information. Submitting a ticket to report that you see the following message gives no useful information to assist you.
WHMCS by default doesn't display details about errors. To get the actual error, we need to look at the two options in Setup > General Settings > Other that are self-explanatory.
First you should go with Log Errors that make it so WHMCS logs error details in Utilities > Logs > Activity Log. Bear in mind the change is not retroactive. You need to cause the error in order to have it logged.
In other terms, if you're experiencing a blank page, refresh it. This triggers the error that ends up in the Activity Log. The same applies to errors that trigger when specific events occurs. You simply need to reproduce them.
If the log doesn't provide useful information, enable Display Errors. This prints the verbose logging of error on screen like the one visible in the following screenshot.
Keep in mind that you must be logged in as administrator to see it. For security reasons WHMCS blocks the view of this page to visitors and users.
If none of these options work for you, there's a third method. At the very end of your configuration.php (root directory of WHMCS) copy-paste the snippet provided below.
$display_errors = true;
$display_errors = E_ALL;
This produces the same effect of Display Errors. Don't forget to remove it when finished. Now let's see what are the most common causes of problems.
Here we don't cover WHMCS errors and ones caused by other third-party modules and templates. We focus on the most typical causes of errors that can be related to the use of our modules.
SQL syntax errors are mostly due to MySQL Strict Mode being enabled. Strict mode controls how MySQL handles invalid or missing values. Simply put, it forces developers to write better SQL statements.
We can all agree on the fact that all softwares should be "strict mode" compliant but here is the thing. WHMCS does not support strict mode. WHMCS itself says that it is important that MySQL Strict Mode is disabled for the proper operation.
That being said, there is no point for us to make our modules "strict mode" compliant as they are installed in WHMCS that doesn't follow these rules.
If you're asking why you haven't seen any error yet from WHMCS regarding strict mode, bear in mind that there are such errors. It's just that they don't happen in what you can "see" with your browser. They predominantly occur during automations.
On the other hand in our modules, especially Billing Extension, we perform super-complex SQL queries that are more inclined to cause an error. In conclusion make sure strict mode is disabled on your server. This is a requirement of WHMCS.
If you experience an error in SQL syntax regarding "only full group by", this is caused by your server misconfiguration.
In the previous chapter we underlined that WHMCS is not compatibile with MySQL Strict Mode. Similarly to this, WHMCS does not support ONLY_FULL_GROUP_BY. This mode must be turned off entirely as follows.
- Open phpMyAdmin and select localhost
- Click on Variables menu
- Look for SQL Mode and click on edit button
- Remove ONLY_FULL_GROUP_BY and save
A fatal error involving ionCube Loaders generally means that you downloaded the wrong package from our website. As we say in Modules' installation guide, each module is available in multiple packages:
- PHP 7.2+
- PHP 7.1+
- PHP 5.6+
With the exception of Bundle that can be installed almost on any PHP version you want, other packages are not interchangeable. To put things in perspective:
- For PHP 5.6 and 7.0 download PHP 5.6+
- For PHP 7.1 download PHP 7.1+
- For PHP 7.2 and newer download PHP 7.2+
Please, make sure to always download and install the correct package. For more details we created an article where we help you choosing the right package for download.
You could encounter problems if your server does not allow short open tag. PHP opening tag is
<?php but it can also be written as
<? (short tag).
To avoid any possible issue, we always use the long form but some third-party components we use in our modules, could prefer the short version. We have no control over them so if you're having errors about opening tag, simply allow short tags on your server.
Using auto_prepend_file or auto_append_file PHP functions surely cause a fatal error. Please, disable them otherwise none of our modules can work. This also applies to other third-party modules but that's another story for another time.
Make sure that base_64_encode and base_64_decode PHP functions are available on your server. Without it most of WHMCS modules including our ones can't work properly.
If none of the solutions above work, include all details of the error using bug reporting tool or submitting a support ticket. Also don't forget to revert back all changes you made to log and view errors.