Blog Post

WordPress Debug mode: Benefits and Pitfalls

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 cause more problems than it can help solve.

PHP Errors

Before we proceed, here is a short overview of standard PHP errors that can be encountered while running any PHP code, including WordPress.

  1. Notices: These errors are trivial and non-critical and are not displayed by default. They also can’t stop code execution (variable not defined yet, for example).
  2. 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).
  3. Fatal Errors: These are critical errors displayed and will also stop code execution. They point to a problem that prevents further execution (e.g., a missing class or function).
  4. Parse Errors: These are critical errors caused by invalid PHP code (missing semi-colons or other unexpected characters).

WordPress Error Handling

By default, WordPress debug mode is disabled. Depending on server settings, the server can still log errors in a centralized error log or logs placed in directories where the errors occurred.

To enable WordPress debug mode, add the WP_DEBUG constant set to TRUE into the wp-config.php file. You need to have this line in your wp-config.php:

define('WP_DEBUG', true);

This will activate error reporting for all errors, including strict and deprecated ones. Two more debug constants can be used if WP_DEBUG is active:

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

The first one will activate (or force) the display of errors on the screen. The second one will activate logging errors into a file. This file will be debug.log in your website’s 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 will not make any difference, and you will see no errors. But as soon as you start adding plugins and changing the theme, things will get very, very different.

The main reason for using debug mode is to discover errors thrown by the PHP code. If you are working with a development installation (your localhost or server test environment), it’s highly recommended that you use WordPress Debug mode. If you write your own plugins or themes, it is essential to use debug mode.

Debug mode is on, what now?

For live environments, WordPress Debug mode should be used only if you get a 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 the content, you either get 500 internal server errors or a 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 the problem.

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 files in wp-admin or wp-includes folders. If used typically, there should be no errors there, so that points again to a plugin that uses some WordPress function or class incorrectly. Debugging, in that case, can be a bit harder, but this will always (well, almost always) help:

  1. Disable all plugins.
  2. If the problem is still there, the theme is causing it, disable it to check.
  3. If the theme is not the problem, enable plugins one by one.
  4. After enabling a plugin, try to repeat the operation that caused the error.
  5. Once you see the error again, the last plugin you activated is at fault.
  6. Contact the plugin author with the error message and description of what you tried to do.
  7. Wait for the solution… Or
  8. Try to fix it yourself if you are a developer or have PHP experience.

Fatal Error: Out of Memory…

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 or 128M should be enough for anything. If you have more than 40-50 plugins, you could need more than that.

However, this error can also indicate a memory leak in some plugins. If you increase memory to 256M or more, and you still get out-of-memory errors, the memory leak is most likely due to some endless loop in the code or SQL queries that return massive datasets that can’t fit in memory. Detecting which plugin leaks memory is usually easy to see. If you look at the 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 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:
Increase PHP Memory Limit

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 a few of those), and you have to wait for them to do it. There is only one solution in this case: change your hosting company. Whatever you are paying for hosting, I am sure that there are at least 5 other companies with the 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. Look at the screenshot below, and you will see all sorts of errors: notices, deprecated use, and warnings. They are not critical, but when debug mode is on, you will see it all, making debugging almost impossible.

Debug Notices
Debug Notices printed on the page

Many plugins and themes (this can be applied to commercial ones) for WordPress will generate these non-critical errors when used. Some developers don’t care about these, and they will leave them in the code, and that points to another problem: if they didn’t care to fix these non-critical errors and warnings, what else in their code could be a real problem? As I said before, development should be done with debug mode, and these notices will be visible. If they left them in the code, they didn’t see them, which means they didn’t use debug mode. For my part, I try to fix every notice and warning I have in my plugins (even the most minor ones: initializing variables and arrays), and my plugins will not throw such notices (if you find any that I may have missed, please report it). This problem is further compounded by the introduction of PHP 8, and each new version has introduced deprecation changes and other things that have increased the number of notices and warnings displayed. It is essential to test all the code properly with both PHP 7 and PHP 8 and ensure those changes are incorporated correctly in the code.

So, you activate debug mode and 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 a good idea. Waiting for developers to fix their own plugins? Well, that can take a long time… After all this, debug mode can be tricky to use since it can be rendered useless when you have old and poorly maintained or poorly-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 do I use debug mode to display these error messages without messing with the page content? Thankfully, there is a way. PHP provides methods to override default error handlers and ‘hijack’ their output to hide it or use it for other purposes. You will not write your own handlers every time; the best is to use a plugin that will do that for you.

Since Dev4Press focuses on WordPress development, we needed a comprehensive and easy-to-use debugger. Dev4Press’s plugin, DebugPress, is free and available in the WordPress.org plugins repository.

debugpress 35
DebugPress Popup Debugger panel

The plugin debugger is activated through the green/yellow/red (depending on errors logged) bug button at the top of the screen (can be repositioned or placed in the admin bar). It can have many tabs with all sorts of data. All notices, warnings, and errors will be in the Errors tab; you can review it from there; no more mess in the page content.

Conclusion

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, what you get from it will be helpful to developers of the theme or plugin that is causing problems.

Please wait...
DebugPress plugin for WordPress
Powerful Debugger Popup plugin for WordPress

DebugPress is an easy to use plugin implementing popup for debugging and profiling currently loaded WordPress powered website page with support for intercepting AJAX requests.

About the author

Milan Petrovic
Milan Petrovic

CEO and Lead developer of Dev4Press Web Development company, working with WordPress since 2008, first as a freelancer, later founding own development company. Author of more than 250 plugins and more than 20 themes.

Subscribe to Dev4Press Newsletter

Get the latest announcements, release digests, promotions and exclusive discounts, and general Dev4Press-related news straight into your mailbox.


This form collects your email (optionally your name) for the purpose of sending you newsletters. Check out our Privacy Policy for more information on how we store and manage your data. We will not send you any spam. Newsletters are sent 2 to 4 times every month.

Latest From The Blog

plugins release sweeppress pro 5 2

SweepPress Pro 5.2

Version 5.2 is a minor scope update that brings a new shared library, expanded lists of values for CRON, options, metadata detections, improvements to the CRON panel filtering, and a few fixes.
plugins relase gd topic prefix pro 4.0

GD Topic Prefix Pro 4.0 for bbPress

A brand new major update for GD Topic Prefix Pro for bbPress is released, and version 4.0 is a smaller scope update that completes all the previous development plans, updates the shared library, and more.
plugins relase gd power search pro 2 6 lite 2 0

GD Power Search Lite 2.0 & Pro 2.6 for bbPress

The fully updated Lite version overhaul is finally ready and available as version 2.0, based on fully updated Pro version 2.6, also available now. This includes various updates and improvements and the latest version of the new shared library.

Leave a Comment

Grammarly - Number 1 Writing App
WP Rocket - Make WordPress Load Fast in a Few Clicks
0
0
0
0
0
0