WordPress Debugging: The Essential Guide

Regardless of what level of WordPress developer you are, there is one problem you’ll constantly face: bugs. Even the most seasoned developers produce bugs. Debugging is a great way to grow as a developer. It will help you learn even more about the WordPress platform, too.

If you have prior programming experience, chances are you’ve had errors upon compilation or runtime. Unless you threw in the towel and tossed the project, you probably spent time running through the code and tracking the problem down. You’ll find that debugging experience is the same with WordPress.

Unlike other common programming languages, WordPress errors are not simply displayed on the screen. This is because debug logs often contain sensitive information, like database credentials. WordPress will drop those logs into files on your server that are inaccessible to the public.

Fortunately, unlike the early computers that weighed thirty tons, you won’t have to literally remove dead bugs from your computer to accomplish this! Now that we have some context let’s take a more technical look at what goes into the WordPress debug process.

WordPress and PHP

As you likely know, WordPress is developed using the PHP Hypertext Preprocessor (PHP), which is a constantly evolving server-side scripting language for generating web pages dynamically or “on the fly” as they’re requested.

Currently, the latest PHP 8.x compatibility is not officially supported by WordPress, but it is functionally compatible. Older PHP 7.4 and earlier code will continue to work with many hosting environments for some time, but some have moved on the require PHP 8, and eventually, all hosts will.

That means that the official WordPress guide on debugging and the official PHP debugging guide will be excellent resources to help you along the way.

To debug at all, WordPress requires you to have a global PHP variable defined. We’ll go over exactly how to do that in the next section.

WordPress Debug Explained

It’s important to distinguish how the PHP debugging process differs from the WordPress debug process. With vanilla PHP, only two types of errors are shown by default.

One is a “fatal error,” meaning it’s so severe that the page cannot load. The other is simply showing the user a blank page if there’s a “sensitive fatal error.” In other words, PHP knows that printing out the full error message could pose a security risk. These settings can easily be modified in PHP itself.

WordPress, conversely, is a bit wordier when it comes to debugging. If you enable WordPress debugging and do not customize it, every level of error, warning, and even informative items for developers will be displayed. That means everything from fatal errors to a technical message about how you should optimize a section of JavaScript will be shown. While this is extremely helpful for developers, it’s probably not the best content to show users.

Another unique feature is that you’ll be notified about WordPress-specific PHP functions that have become deprecated. Functions that have become deprecated may still work now, but support will be dropped for them in the future. This also typically means there’s a better, faster way of accomplishing the same process.

We know you probably aren’t excited about debugging WordPress, but it’s critical to maintain a functional blog or site. Before you begin editing files, though, be sure to use a trusted WordPress backup plugin to archive your site first. This way, if you accidentally make your site inoperable, you can restore everything in just a few clicks!

Now, let’s take a look at how we can get rolling!

How Do I Enable Debugging in WordPress?

To start the WordPress debug process, we’ll need a couple of lines of PHP.

Fire up your favorite text editor (as long as your favorite text editor isn’t the Windows Notepad!). If you need one, Notepad++ is a commonly used, open-source text editor that supports almost every programming language.

Next, download a copy of your wp-config.php file. Do not edit the original file! We’ll upload the modified version once we’ve finished.

Once you’ve opened up wp-config.php in your text editor, you must add the following line of code. First, search for it to ensure you don’t already have it; PHP becomes very unhappy if you define the same variable twice!

define( 'WP_DEBUG', true );

All this line of code does is set that global PHP variable called WP_DEBUG to the boolean value of true.

Likewise, if you wanted to turn the WordPress debug feature off, you’d just put in the opposite line of code:

define( 'WP_DEBUG', false );

This turns on debugging, but that isn’t too helpful if we don’t know how to find the information that’s output!

Where is the WordPress Debug Log?

There are technically two answers to this question, and the exact answer depends on your choice.

As we said, one way is to drop in define( 'WP_DEBUG', true );. This uses the default WordPress debugging log settings, which automatically creates a file if it doesn’t exist (or appends to it if it does) in the location wp-content/debug.log.

However, you might want it in a different location for several reasons. For example, you may wish to have it in a location where a third-party debugging tool can access it. To customize where the debugging log is put, you can enable debugging like this:

define( 'WP_DEBUG_LOG', '/best-wp-dev/errors.log' );

WordPress Debug Log Explained

The level of detail of information in your WordPress debug log depends on how you configure it. If you enable it without additional modifications, you will log almost every event that causes an error, uses a deprecated function, or isn’t optimal.

Since WordPress is built on top of PHP, your log will show every PHP error and warning thrown. It also will contain the date, time, and IP address associated with each event. Unfortunately, you’ll also see PHP’s (very) verbose output about many things, like code styling it doesn’t like, data validation it feels should be strengthened, and more.

Especially for people just getting started debugging WordPress, looking at the log file can be quite overwhelming. However, you should remember that only a few items are necessary.

Debugging vs. Logging

Though they aim to accomplish the same goal, you must understand the difference between debugging and logging. In other words, the line define( 'WP_DEBUG', true ); does something completely different from the line define( 'WP_DEBUG_LOG', true );.

In no event should you use define( 'WP_DEBUG', true ); on a site that’s accessible to the public. When used by itself, this command will print debugging messages. This does not log anything and will output information that could be used to steal data from your site(s). In conjunction with a solid WordPress security plugin, ensuring this is not turned on will thwart most attempted cyberattacks.

Solid Security – Password, Two Factor Authentication, and Brute Force Protection

Debugging WordPress Without Risking Security

You will need to debug your site regularly. However, you probably don’t want to constantly add and remove lines of code from your wp-config.php file.

Thinking through the process, we will first need to enable debugging in general. Then, we’ll need to make sure we log errors to make fixing them possible. However, we do not want to show these errors to the general public. Remember that we must suppress both standard PHP and WordPress-specific errors from being shown.

Sample Secure WordPress Debug Code

Using the process outlined above, here are four lines of code that can get you started safely debugging your site!

define( 'WP_DEBUG', true );

define( 'WP_DEBUG_LOG', true );

define( 'WP_DEBUG_DISPLAY', false );

@ini_set( 'display_errors', 0 );

The first three lines above set global PHP variables that WordPress pays attention to. We’re making debugging possible, setting up our logging functionality, and then turning off WordPress-specific errors.

Chances are that the fourth line looks like it came out of left field! This line is to address PHP errors that WordPress doesn’t handle. It’s the last base to cover to ensure that malicious users don’t get access to sensitive site information.

How Do I Fix a WordPress Debugging Error?

Quite often, developers will use those four lines of code we went over. They’ll experience an error, such as a database connection failure, but nothing will be in the debugging log. This is because WordPress has different global PHP variables for different debugging methods.

Let’s look at a few scenarios where you’ll need to add a few more lines to your wp-config.php file to debug WordPress properly.

Debugging WordPress JavaScript

If you have a WordPress site, it is highly likely to use JavaScript. For newer developers, this is essentially the language that powers interactive elements of sites. JavaScript is notorious for being quite tedious to debug. This is because modern sites often use frameworks on top of JavaScript, further complicating warnings and error messages.

Unfortunately, that’s not the only thing that makes debugging WordPress JavaScript difficult. There are two basic forms of JavaScript: asynchronous or “AJAX” and regular JavaScript. Regular JavaScript operates linearly; it won’t run one function until the execution of the one before it has concluded. Though this may have worked out in the earlier days of the web, it doesn’t cut it for web applications.

AJAX, on the other hand, operates in the background on your WordPress site. It allows you to run JavaScript functions and wait for their output, but it doesn’t prevent other functions from running. It’s often necessary to prevent sites from locking up.

WordPress has us use another PHP global variable to say we want to debug scripts because this debugging method outputs a huge amount of data.

WordPress has us use another PHP global variable to say we want to debug scripts because this debugging method outputs a huge amount of data. It’s also because JavaScript and CSS run on the client side, while PHP runs on the server side. To output every error WordPress runs into due to JavaScript and CSS, add this line:

define( 'SCRIPT_DEBUG', true);

This will show both JavaScript and CSS (stylesheet) errors. It can also help with those more complex AJAX operations.

Fixing Data Issues

Almost every website grabs information from a database. WordPress has several databases; some sites store them on separate servers, while others keep them on the same server. Since all configurations are different, there’s always a chance of something going wrong in your database connection.

If you get an error message saying that WordPress couldn’t connect to a database, or you notice that data isn’t being pulled correctly, you probably will need to debug. Using the standard WordPress debug variables, you’d likely notice that nothing would be logged when you encountered a database-related error.

This is because WordPress partitions database-related errors away from all other errors. Database error messages often contain sensitive information, and WordPress developers wanted to ensure you don’t accidentally divulge private information to the public!

To start debugging WordPress database problems, you will need to add yet another line to your wp-config.php file:

define( 'SAVEQUERIES', true );

Diving Into Database Debugging

Unlike our other global WordPress debug variables, we must pay special attention to this one. “SAVEQUERIES” tells WordPress we want to see every query run and its results returned. This will substantially harm sitewide performance! Be careful not to run this on your server at peak times, and turn it off as soon as you don’t need it.

It also stores its output a bit differently. WordPress uses a PHP array of strings that you will need to access to see database debugging information. It’s located in the PHP global variable called $wpdb and in the member array called queries. You can reach it by printing the contents of $wpdb->queries

Debugging WordPress Plugins

One prime advantage of WordPress over other platforms is its rich library of plugins that can do almost anything. You might be reading this and already getting a headache thinking about the logistics of constantly debugging plugin files. Thankfully, some plugins can help us with debugging WordPress! Two particularly popular ones make it a breeze.

WP Debugging

This is one of the best-known WordPress debug plugins on the WordPress site. It essentially automates the processes we talked about already. With a few clicks from your dashboard, you can turn all of these PHP global variables on and off on your site.

When you install this plugin, you also install a series of plugins on which it depends. As a whole, they let you log errors and help you interpret them.

This tool is great for enabling the debugging process, but to debug your plugins and to easily look at database-related WordPress debug information, you’ll need another plugin, too.

The Debug Bar

As its name suggests, the Debug Bar is simply a bar on the admin panel of your WordPress site. It can be used in conjunction with the WP Debugging tool.

It has tools for more advanced developers, allowing them to view the cache, queries that have been output, the results of queries, and more advanced information. As we mentioned, WordPress drops all database debugging information into a PHP global variable.

You must iterate through that array in a custom PHP file to view that information. This plugin gives you an easy alternative. It prints this information out for you in a format that’s quite easy to read and understand. It even gives you some tips on how to optimize your database calls!

Debugging WordPress Themes

Debugging WordPress themes typically involves enabling the PHP global variable regarding scripts. This is because themes utilize client-side JavaScript and CSS.

First, ensure that it’s a theme that you authored. If it’s a third-party theme experiencing problems, you’ll need to contact the theme’s author. It might be like trying to find a needle in a haystack if you attempt to debug the theme yourself!

If it’s your theme, follow the steps we discussed to enable debugging. Perform whatever action causes you to notice the bug. You can also enable the Developer Console within your web browser by pressing F12. This shows more client-level error messages that can help in the process.

After performing actions on your theme that lead to errors, consult the log. There should be detailed information there on what’s causing the errors. It’ll take a few JavaScript and/or CSS tweaks to get everything back to normal!

Debugging WordPress Critical Error

If a plugin, theme, or other custom content generates an error causing your WordPress site to fail, your site should email you regarding the failure. Especially for newer webmasters, this can be distressing.

There’s no need to worry, as you can quickly follow this chain of steps to resolve the issue!

1. Make sure that you have turned on WordPress debug mode.
2. Access your error log. It should have detailed information about the fatal error. If so, search for the exact error code online.
3. Check your version of PHP. If it isn’t what WordPress currently requires, simply updating your server’s PHP version could fix the issue.
4. If you still have no luck, go through your plugins. Turn all of them off. If the site works, that means a plugin caused the issue. Go through them one by one until you find the problem plugin. Contact whoever wrote it and ask them to fix it.
5. It could be a theme-related issue if you still haven’t found the problem. Try reverting your current theme to the default WordPress one. If that makes your site work, you must change themes temporarily until your current theme’s author resolves the issue.
6. No dice? Put your error up on the WordPress developers’ forum. There are plenty of users who would be happy to help you.

Wrapping Up

Debugging WordPress can help you solve many issues you encounter. It can tell you what plugins or themes have bugs and help you fix them. As a WordPress Developer, debugging helps you become a better developer, and it also helps you produce clean, quality code.