How to Enable and Use WordPress' Debugging Feature

One of the most frustrating aspects of running a website is trying to fix errors when they pop up. Various issues can cause parts of your site – or the entire thing – to cease to work out of the blue. This can lead to you spending hours trying to diagnose and solve the problem.

Fortunately, WordPress includes a debug mode that enables you to troubleshoot errors efficiently (and preserve your sanity). The mode is turned off by default, but it's easy to enable, and the logs it produces are incredibly detailed. If you know how to access them, troubleshooting can become a breeze.

In this article, we're going to talk more about WordPress' debug mode and how it works. Then we'll teach you to enable it, access your error log, and interpret the results. Let's get to work!

What the WordPress Debugging Mode Is (And How it Works)

Error logs can may look indecipherable, but in most cases they're not as difficult to interpret as you might think.

When the WordPress debugging mode is turned on, your website will automatically log any errors that occur. The resulting logs are incredibly detailed, which makes them a boon when it comes to troubleshooting. This fact can also make them overwhelming to interpret, but they're usually not as difficult to read as you might assume.

Enabling the WordPress debugging mode requires you to make a small change to a PHP file. You don't need to know PHP to make the necessary change, but it can be helpful when it comes to interpreting your error logs. The logs themselves often mention the exact files that are causing problems, however, as well as the offending lines of code within. With that information, you can pinpoint the source of an error and prepare to solve it, even without much technical experience.

Another benefit of using the debugging mode is that it doesn't impact your website's performance. Even though your site is logging every event that occurs in the background, it should still be as fast as ever. However, it is highly recommend that you only use the debugging tool on a staging website. It was not intended to be used on a live site, as the information contained in the error logs can be sensitive and could become accessible to your users.

How to Enable and Use WordPress' Debugging Mode (In 3 Steps)

As we mentioned earlier, using WordPress' debug mode means you'll need to interact with a few PHP files. However, the process of turning the feature on is quite straightforward, even if you're not familiar with the language. Let's break it down step by step.

Step 1: Access and Modify Your wp-config.php File

The wp-config.php file is one of the core files of every WordPress website. It contains some of the platform's primary settings, and enables your site to establish a connection with its corresponding database. To find and access it, you'll need to use an FTP client, such as FileZilla.

Go ahead and open your client, then log into your website using your FTP credentials. If you don't know what they are, you should be able to find them on your web host's control panel or within one of the emails you received when you signed up for your hosting service.

Once you're in, look to the lower-right side of the screen and locate the public_html or www folder. This is the 'root' of your website, so to speak, and it's where all your WordPress files reside:

Enter that directory now, and look for the wp-config.php file within. Right-click on it, and choose the View/Edit option. This will open the file using your local text editor, enabling you to make changes.

Scroll down to the bottom of the file, and look for the line that reads /* That's all, stop editing! Happy blogging. */. You're going to paste the following code snippet right above it:

define('WP_DEBUG', true);

define('WP_DEBUG_LOG', true);

This code tells WordPress to turn its debug mode on, and to log any errors it finds in a file that you can access at your leisure. Simply save the changes to your wp-config.php file, and move on to the next step.

Step 2: Locate and Read Your WordPress Error Log

The WordPress debug mode is now active, so you can access your error log any time you want. Of course, it will take a little time for data to start collecting, so you may want to come back to this step in a day or so.

When you're ready to check out your error log, return to your FTP client, access your website, and open your WordPress root folder once again. Inside, this time look for the wp-content folder. Open it, and you should find a file called debug.log:

This is the error log you're looking for. Go ahead and open it using the View/Edit option in your FTP client. You should see a long list of events as soon as it pops open, which can look intimidating. There's no need to worry, however, as we'll talk about how to interpret this log in the next step.

Step 3: Use the Error Log to Perform Troubleshooting

Let's break down how to interpret your error log, using a real example. Recently, we ran into this Error establishing a database connection issue on one of our websites:

According to the error screen, there are several possible causes for this problem. Luckily, we have an error log that can shed light on the issue. We opened our own debug.log file following the instructions above, and here's what it logged each time we tried to access the website:

If you pay close attention, you'll see that the event mentions the phrase "Access denied". From this, we can gather that the database is up and running, but there is an issue with our credentials. Once we found the source of the problem, we just had to correct our database access information through the wp-config.php file, and we were good to go.

This is just one example of how handy WordPress error logs can be. Aside from troubleshooting general issues, they're also a great help if you're developing your own themes and plugins, since they'll let you know if you're doing something wrong. With a little patience, you can use your log to diagnose and fix just about any issue.

Conclusion

For most of us, troubleshooting can be frustrating. You'll often need to test multiple solutions before you land on the one that works, because you don't have enough information to pinpoint the source of the problem. Tools such as WordPress' debug mode and its resulting error logs are invaluable in these situations, because they can save you time and headaches.

WordPress' debug mode is turned off by default for new installations. However, you can enable and start taking advantage of it in three short steps: