Finding Hidden WordPress Errors With Debug Logging

An exotic squirrel hiding in a tree.


Posted On:

It would be really awesome if your WordPress site just worked, always. In reality a WordPress site is a combination of an infinite number of plugins and themes and something is bound to go wrong at times. Knowing how to troubleshoot problems is an important skill if you make and maintain WordPress sites.

The WordPress ecosystem is full of great resources for getting help, and if you are paying for a plugin or theme, you should expect support from the developers. Being able to tell the developer what went wrong, with specific errors and warnings will go a long way in getting a remedy quickly.

The more dynamic and AJAX driven a site is the harder it is to see errors, even with WP_DEBUG enabled. In this post I’m going to show you how to use the debug logging features in WordPress to record and detect errors that might not otherwise be visible to you.

You’re probably reading this because you have a problem with Caldera Forms and you’re not sure what it is. Did you know when you have the Caldera Forms Pro API client active, we log errors for you? Saves a lot of time in getting support.

Simplified Options, Even Better Support

Editing Files In Your WordPress Site

Depending on how your site is setup there are different ways to edit files. You may have FTP access or be able to use the cPanel file manager to edit files.

Editing files is always risky, make sure to back up your site first. Also, it is safer and easier to edit files when developing your site locally. DesktopServer makes this really easy.

Setting Up For Debugging

Every WordPress site has a file called “wp-config.php”. This file holds the configuration details for your WordPress site. In it you tell WordPress how to connect to your database and other important details that make a WordPress site go. This file is either located in the root directory of your site, or one directory above.

Most settings in wp-config are made using PHP constants. PHP constants are values that you can set once and use in any other file in the application. To create a function and set its value, we use the function define(). For example:

define( 'WP_DEBUG', true );

The code I just showed you defines the constant “WP_DEBUG” and sets its value to true. The affect of adding that to your wp-config is that your site is now in debug mode. This will cause all PHP errors, warnings and notices to be displayed on the screen. This is really helpful in your staging and local environment, but not a good idea in your live site.

By the way, if you are getting the so called WordPress white screen of death, it’s likely beacuse your site has an error and WP_DEBUG is not set to true. If you change it to true, you should see a fatal error, which you can now fix.

It is very important to know that you can only define a constant once. If you already had WP_DEBUG defined in your wp-config adding a second definition will break your site.

Using Debug Logging

When you are are in debug mode, you can actually turn off display of errors, by adding another constant to your wp-config file.

define( 'WP_DEBUG_DISPLAY', false );

Now errors, warnings, and notices will not be shown on the screen. This is useful as the messages can cause issues of their own, especially if your form uses AJAX for processing, which Caldera Forms does by default.

Of course, we still need to see these errors. That’s where the third useful constant for debugging comes in:

define( 'WP_DEBUG_LOG', true );

Now, with these three constants set, you will not see any error, warning or notice on the screen, but they will be written to a special file. This file is called debug.log and it is located in your content directory. The content directory is called “wp-content” by default but its name can be changed — with a constant in wp-config.

Using Debug Logging

Now you should have this in your wp-config. Make sure these constants were not already there and then save.

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

Now you can test your site, whatever part of it is causing problems and check the log for new entries. Whatever you find, share it with the most applicable support resource.

Next Step: Browser Errors

Now you’ve checked for errors from your server. If you found the error, this is probably your culprit – tell us what you found and we can provide guidance on what to do next. If you found nothing, but the error persists, your problem may be a client-side error (an error in your browser). In this case, go to this guide to find your browser errors.

Found it? Great! Tell us what you found and let’s get solving your problem.

If you found nothing, we want to take a look. Something is wrong and we want to solve it for you. Let us know.