Debug WordPress, the right way

Like gremlins in the night, WordPress websites can sometimes get visited by unwanted nasties, errors. When these WordPress gremlins show up, it is very useful to find out what they are and where they come from so that you can banish them from your installation. Wordpress has a special mode for finding errors:

In this short article, we will look at the basics of this magic mode and how to use it.

The first question is how do we activate this magic mode, this shining beacon through the veil of darkness, that will reveal to us any errors in the code that interfere with the normal work of the site? The answer is very simple - and no magic wands needed!

To activate wp_debug, you need to find the wp-config.php file in the root of your Wordpress site, open it and find the following line:

define ('WP_DEBUG', false);

By default, the value of the WP_DEBUG constant is set to FALSE (meaning that it is turned off), we need to switch it to TRUE:

define ('WP_DEBUG', true);

Sumptuously! But let’s not rush to save, but add two more constants that will help us in debugging.

The first of them will be:

define ('WP_DEBUG_LOG', true);

This constant will write all errors and warnings to the error.log file, which will be placed in the wp-content folder. This allows us to easily track errors and the time of their appearance.

The second and last:

define ('WP_DEBUG_DISPLAY', false);

This useful constant will turn off displaying errors on the site, so if the site is currently working and is actively used by users, the visitors will not notice the gremlins. All errors will only be visible in the log file.

So, all together, our changes will look like this:

define ('WP_DEBUG', true);
define ('WP_DEBUG_LOG', true);
define ('WP_DEBUG_DISPLAY', false);

You can simply copy them from here and insert them into your own wp-config.php (replacing or deleting the line defining WP_DEBUG as FALSE).

We can now save our changes and dive into the wonderful world of gremlin hunting, error detection and banishment.

After activating the debug mode, we can explore our realm, looking through the site, trying various functions that might cause an error and bring out a gremlin. This allows us to accumulate information in our debug log. If we immediately see a blank screen (White Screen of Death) or some errors on the main page of the site, then we can open the debug.log file (remember, it’s located in the wp-content folder) and study it carefully.

There are 3 main types of notifications in the error log: 1) Warnings: Warning, for example about using deprecated functions. Warnings don’t stop the execution of the code and won’t cause issues on your site. 2) Notices Just mentions/suggestion that you may have a bug in the code. If you fix it, maybe the site will be more stable or work faster. 3) Errors Serious errors that lead to stopping the execution of PHP code and lead to the appearance of the dreaded white screen of death. We must eliminate them first.

The most common errors that we can find in the debug.log file

Memory exhausted problems

If you see a gremlin like this in the log file:

Fatal error: Out of memory (allocated 3145728) (tried to allocate 2097152 bytes) in ...

or

Fatal error: Allowed memory size of 33424432 bytes exhausted (tried to allocate 1548617 bytes) in ...

Solution:

  1. You need to increase memory_limit to at least 128M-256M (It’s possible to do with the php.ini file, you can read more about this: http://php.net/manual/en/ini.core.php#ini.memory-limit).
  2. Then you need to add the next string in your wp-config.php file:
define ('WP_MEMORY_LIMIT', '256M'); // To increase memory_limit to 256M

You need to save your changes and you can now go to your site, the site should come back to life. Some hosting providers will make this memory limit change for you.

The main algorithm for eliminating errors caused by a specific theme or plugin. In our debug.log file, if we find that a plugin or theme calls fatal errors, then the easiest and most accessible way to stop executing their script is as follows: 1) Using FTP or the file manager provided by your hosting, we find the plugin or theme folder pointed to by the error in debug.log 2) Rename the folder. An easy want to do this is by adding an underscore character at the end of the folder name. Suppose the plugin that caused errors was in the folder wp-content/plugins/custom-plugin, we rename it from “custom-plugin” to “custom-plugin_” 3) Renaming the folder disables the theme or plugin and we can now check the efficiency of our site and/or admin panel.

PHP versions incompatibilities

Often there are problems due to an incompatibility of the code written on older versions of PHP, if you have a newer version of PHP currently active. These errors may look like this:

Fatal error: Uncaught Error: [] operator not supported for strings in public_html\wp-content\plugins\Badplugin\main.php:72

You can see the path to the plugin or theme that is causing this error. To fix it, we use the previously mentioned anti-gremlin method - renaming the folder. In our example, we see that the error is caused by a plugin located in the / wp-content/plugins/badplugin directory, so we rename “badplugin” to “badplugin_” to disable it and then check the availability of the site and admin panel.

If you need the plugin that you renamed, then the next step will be to find out if this plug-in has updates or alternatively you can contact the developers of this plug-in and let them know the problem.

Attempt to use an undeclared function or call a function that has already been declared

A plugin can execute an undeclared (undefined) function and cause an error similar to this:

Fatal error: Call to undefined function cool_function_name () in /home/public_html/wp-content/plugins/another_bad_plugin/functions.php on line 297

There can be a reverse situation when a plugin or theme tries to declare a function that has already been declared earlier by another plugin and then you will see an error of this kind:

Fatal error: Cannot redeclare very_useful_functions () (previously declared in /public_html/wp-content/plugins/well-developed-plugin/modules/main.php:226) in / public_html / wp-content / themes / xxx / includes / plugins /functions.php on line 2431

We solve these problems in a similar way, first rename the plugin folders, and then you can try to update and activate the plugins in the admin panel. Very often these errors occur due to plugins being activated in the incorrect order. For example, if you have a WooCommerce plugin and also a plugin that extends WooCommerce functionality, but during the import process the addon-plugin is activated first, this can subsequently cause such errors.

Use the information from the wonderful debug.log file - this is our main ally in dealing with gremlins in our Wordpress sites. Your next debug ally is Google, just copy paste an error from debug.log to Google and you’ll be sure to find useful information relating to the solution (including this article).

What are your thoughts?