Developers know how to best use debug in WordPress and WordPress WP_DEBUG constant to get through potential problems and bugs their code might have. But, for regular users, using debug mode can be very confusing and can cause more problems than it can help solve.
Before we go on, here is the short overview of common PHP errors you can find while running any PHP code, including WordPress. Besides these 4, there are some 8 or 9 more error types, most of which you will not see if your PHP is installed properly and is not unstable build.
- Notices: These errors are trivial and non-critical, and these errors are not displayed by default and they can’t stop code execution (variable not defined yet, for example).
- Warnings: These are errors that also don’t stop code execution, but they are displayed to the user since they point to a code problem that can cause further issues (failed to include file, for example).
- Fatal Errors: These are critical errors that are displayed and that will also stop code execution. These errors point to a problem that prevents further execution (missing class or function, for example).
- Parse Errors: These are critical errors that are caused by invalid PHP code (missing semi-colons or some other unexpected characters).
WordPress Error Handling
By default, WordPress debug mode is disabled. Error handling and display depends on the server settings. In most cases, this means that errors will not be displayed (even fatal errors), but they should be logged into the file (again, depends on server settings, and it can happen that logging of errors is disabled).
To enable WordPress debug mode, you need to add WP_DEBUG constant set to TRUE into wp-config.php file. You need to have this line in your wp-config.php:
This will activate error reporting for all types of errors including strict and deprecated errors. There are two more debug constants that can be used if WP_DEBUG is active:
define('WP_DEBUG_DISPLAY', true); define('WP_DEBUG_LOG', true);
First one will activate (or force) displaying of errors on the screen. The second one will activate logging errors into the file. This file will be debug.log in your website wp-content folder.
Why use WP Debug mode?
By default, if you don’t make changes to WP core files, and you don’t have any plugins or third party themes, active WordPress debug mode is not going to make any difference and you will see no errors. But, as soon as you start adding plugins and change the theme, things will get very, very different.
Main reason for debug mode is to discover errors thrown by the PHP code. If you are working with development installation (your localhost, or server test environment), it’s highly recommended to use WordPress Debug mode. If you write your own plugins or themes, it is essential to use it.
Debug mode is on, what now?
For live environments, WordPress Debug mode should be used only if you get broken website or no access to it at all. The typical case is that you open your website (any page or only some pages), and instead of content you either get 500 internal server error, or you get the blank screen. In most cases, if the server is set correctly, errors will be logged into the file and you need to check error logs to find out what the problem is. But, if that is not the case, enable WordPress Debug mode through wp-config.php, and you will be able to see what the problem is.
When you get the error, that error includes the path to the file where the error has happened. In 90% of cases, the error is caused by some plugin. But, very often, you will see that error is in some WordPress file in wp-admin or wp-includes folders. If used normally, there should be no errors there, so that points again to a plugin that uses some WordPress function or class the wrong way. Debugging, in that case, can be a bit harder, but this will always (well, almost always) help:
- Disable all plugins.
- If the problem is still there, the theme is causing it, disable it to check.
- If the theme is not the problem enable plugins one by one.
- After enabling a plugin try to repeat the operation that caused the error.
- Once you see the error again, the last plugin you activated is at fault.
- Contact plugin author with the error message and description of what you were trying to do.
- Wait for the solution… Or
- Try to fix it yourself, if you are a developer or have PHP experience.
Fatal Error: Out of Memory…
Typical errors you will discover like this, include famous PHP is Out of Memory error, that many users don’t understand at all. When you see this error don’t panic: you only need to increase the available memory for PHP. In most cases, the server was configured to use 32M (standard values), but WordPress with several plugins will need more. So typically, 64M should be enough for anything. If you have more than 40-50 plugins, you could need more than that.
But, this error can also point to a memory leak in some plugins. If you increase memory to 128M or more, and you have 10-15 plugins, a plugin or theme you are using is bad, and it leaks memory most likely due to some endless loop in the code or greedy SQL queries that return too many results or for some other reason. Detecting which plugin leaks memory usually is easy to see. If you look at full error description you will see where the problem occurred, and that will include the path to the file, and that path includes the folder name of the plugin (or theme). Again, the memory leak is not the same as having just too little memory allocated. Any WP installation should use 64M to 128M, more than that can point to a leak.
Here are several methods for increasing PHP memory:
And once again, hosting company comes to the stage, because some of them will not allow you to change PHP memory on your own (or at all, yes I have seen few of those), and you have to wait for them to do it. In this case, there is only one solution: change your hosting company. Whatever you are paying for hosting, I am sure that there are at least 5 other companies with same prices that will not limit you in using some basic things like memory allocated to PHP.
And now Pitfalls
Yes, this all looks great, enable WP Debug mode and you will find the problem. And what if you find too many problems? Finding fatal errors is one thing, but enabling debug mode will open the door for all other error types to the surface, even if they are not critical. Take a look at the screenshot on the right, and you will see all sorts of errors: notices, deprecated use, and warning. They are not critical, but when debug mode is on, you will see it all, and this can make debug almost impossible.
From experience, 95% of all plugins and themes (this can be applied to commercial ones) for WordPress will generate these non-critical errors when used. Most developers don’t care about these, and they will leave in the code, and that points to another problem: if they didn’t care to fix these non-critical errors and warnings, what else is in their code that can be a real problem? As I said before, development should be done with debug mode on, and these notices will be visible. If they left them in the code, they didn’t see them, and that means they didn’t use debug mode at all. For my part, I try to fix every notice and warning I have in my plugins (even most minor one: initializing variables and arrays), and my plugins will not throw such notices (if you find any that I may be missed, please report it).
So, you activate debug mode, and you find yourself drowning in the pool of notices all over the screen, and you have no idea where to begin. You can go through each plugin code to fix the problems, but that is not really good idea. Waiting for developers to fix own plugins? Well, that can take a long time… After all this, you see that debug mode can be tricky to use since it can be rendered useless when you have old and not maintained or not very well written plugins in the first place. You can combine display and logging of errors, but for non-developers and less experienced users, debug mode can be impossible to use.
There must be some easier way?
How to use debug mode and how to get these error messages displayed without messing with the page content? Thankfully there is a way. PHP provides methods to override default error handlers and to ‘hijack’ their output to hide it or use for some other purpose. You are not going to write own handlers every time, best is to use a plugin that will do that for you. The best free plugins that can do this is Debug Bar. The main issue with this plugin is that is not maintained regularly and might not work as expected with newer WordPress versions.
Since WordPress development is what Dev4Press is all about, we needed a debugger that would be comprehensive and easy to use. So, Dev4Press own plugin GD Press Tools Pro contains Debugger.
The plugin debugger is activated through the green/yellow/red (depending on errors logged) bug button in the top of the screen (can be repositioned). It can have many tabs with all sorts of data. All notices, warnings, and errors will be in this tab,and you can review it from there, no more mess in the page content. All errors are also logged into the database (depending on your settings), SQL queries can be analyzed and formatted and much more. Check out plugin features for more information.
WP Debug mode is a powerful tool to use, but it’s also not something everyone will be able to use effectively. When your site breaks, you will need the debug mode as a first step in determining the problem, and if possible fixing it. At the very least info, you get from it, will be useful to developers of the theme or plugin that are causing problems.