How to debug WordPress issues properly ?

Finding an error in your WordPress(.org) site, can sometimes be a pain in the ass. That’s why I wanted to write somewhat of a step by step plan on how to find the error.

This manual assumes you are developing locally and not working on a live/production site. This was written for Mac, but I think the commands on Windows are equal.

  1. Setup debugging settings
  2. Verify debugging settings
  3. Check debug logger
  4. Pinpoint the location of the error
  5. Still an error ?

Setup debugging settings

WordPress’ debug settings are default set to false. So step 1 is to activate all these settings.

Open your wp-config.php in your preferred code editor.
Add the following lines just before it says: “/* That’s all, stop editing! Happy publishing. */”

  1. define( 'WP_DEBUG', true );
  2. define( 'WP_DEBUG_LOG', true );
  3. define( 'WP_DEBUG_DISPLAY', true );

If you’re working on a live site, don’t add define( 'WP_DEBUG_DISPLAY', true );, otherwise your visitors will also see the errors.

Verify debugging settings

Now that we’ve added these settings, we want to make sure they work.

First we open up our terminal and go to /wp-content/.
Then type the following command: tail -f debug.log.

If you get a no file found notice, trigger it by adding a simple, incorrect line of code to functions.php. Just add the following line:

$var1 = $var2;

Then reload your site and you should see a new entry popup in your logger and on your screen which looks something like this: Undefined variable $var2; in functions.php on line {line number}.

If you see an entry on your screen or in your logger, it’s working.

Check debug logger

If your site experiences any troubles this is the first place to look for it, since all (php) errors are logged in this file (when WP_DEBUG_LOG is set to true).

So click around your website or go to the page/post which you think has a problem and keep an eye on your logger.

Pinpoint the error

Most of the errors occur in a theme or in a plugin. To try and pinpoint the location of the error, disable your custom theme and use a default WordPress theme.

Then click around your site to see if the errors still occur and if something pops up in your error logger.

If this doesn’t fix the error, it’s most likely not somewhere in the theme you’re using.

Next step is to deactivate all your plugins.

Does the error still occur ? If it’s gone, re-activate every plugin one by one and check if the error occurs after each plugin you activate.

Still an error ?

Do you still have errors after this and you can’t fix it ? Contact me to see if I can help you out.