How to Troubleshoot WordPress, Easy Step-by-Step Guide

Easily hands down the most common thing that I find myself explaining to WordPress users is how to troubleshoot WordPress in order to find the cause of some issue. And it makes sense if you think about it. WordPress and all of its plugins and themes are made of code. And code is a complex thing. The more code you add to a site, the more likely it is for bugs and issues to happen. And when they do, it can be confusing and frustrating to the average user.

Fortunately, there is a reliable, proven technique for figuring out why any given problem is happening. It’s referred to as “troubleshooting”, a very powerful tool that everyone should have in their belt. This DigWP tutorial explains two methods of troubleshooting using plain, easy to follow steps.

Troubleshooting is something that literally anyone can do. It is a straightforward, proven process that helps millions of people diagnose problems every day.

Table of Contents

• Two different approaches
• Troubleshooting from the top down
  • Example
  • Troubleshooting steps
  • Beyond plugins and theme
• Troubleshooting from the ground up
  • Example
  • Troubleshooting steps
  • Beyond plugins and theme
• Take-home message
• Going further..

Two different approaches

When it comes to troubleshooting WordPress, there are two ways to do it:

• From the top down
• From the ground up

Each of these methods uses basic logic to eliminate variables and determine causality. As one might imagine, either technique has its own pros and cons. In a nutshell, most common method is top-down, which is used to quickly diagnose plugin/theme conflicts, etc. The ground-up method is a more rigorous, clinical approach that generally requires more time.

Let’s take a closer look at each..

• Troubleshooting from the top down
• Troubleshooting from the ground up

Troubleshooting from the top down

Top-down testing is basically:

Temporarily deactivating each of your other plugins one at a time, re-testing the problem/issue after each, until the issue no longer happens. This tells you as quickly as possible which plugin is interfering with normal functionality.

Pros of top-down testing:

• Can be the fastest way of diagnosing issues

Cons of top-down testing:

• May not be feasible to test on a live site
• Can be complicated if lots of other plugins used on site
• May require lots of time if using lots of other plugins

To understand how it works, let’s go thru an example..

Example

Let’s say that you have a plugin named “Amazing Plugin”. It is not working correctly, and you suspect there is some conflict with one of your other plugins or theme. You want to find out why the issue is happening, and hopefully get it resolved. Before contacting the plugin provider, take a few minutes to do some basic testing of your plugins and theme. Doing so will help the support team understand and provide help as quickly as possible.

Here are the magic steps to troubleshoot your setup using top-down troubleshooting..

Troubleshooting steps

To troubleshoot why “Amazing Plugin” is not working using top-down testing, it is necessary to test all other plugins and the theme. It doesn’t matter which you start with, for this tutorial we’ll start with testing the other plugins, as that is where I’ve found most conflicts can happen.

Test your other plugins

1. Deactivate one of your other plugins
2. Re-test if Amazing Plugin is working properly
3. If Amazing Plugin now works, stop; you have found the conflict
4. Otherwise, if Amazing Plugin still is not working, deactivate another one of your other plugins
5. If Amazing Plugin now works, stop; you have found the conflict
6. Otherwise, if Amazing Plugin still is not working, deactivate another one of your other plugins
7. Repeat this process for all of your other plugins, or until Amazing Plugin is working properly

At this point, if the Amazing Plugin is working normally, then the cause of the issue is whichever plugin that was last deactivated. Otherwise, if you get through deactivating all of your other plugins and Amazing Plugin still is not working correctly, it is time to repeat the test with your theme.

Test your theme

If you follow the above steps and deactivate all of your other plugins, and the problem remains, it’s time to repeat the process to test your current theme:

1. With all of the other plugins deactivated, switch to one of the default WP themes (e.g., Twenty Twenty)
2. With the default theme active, try retesting the Amazing Plugin
3. If Amazing Plugin now works properly, you have found the issue: there is some conflict with your theme
4. Otherwise, if you have deactivated all other plugins and switched to the default theme, and the issue persists, then there is something else that is interfering

Hopefully at this point, you have found out which plugin or theme is interfering. If not, then further sleuthing is required to solve the mystery.

Beyond plugins and theme

After completing the above troubleshooting steps, in 99% of the cases I’ve seen, the conflicting plugin (or theme) will be found. If that is not the case, then one of the following must be true:

• Further testing/troubleshooting is required
• The issue is with the plugin itself
• The issue is with WordPress core
• Something else outside of WordPress
• Some combination of the above

So with all other plugins deactivated, and using the default WordPress theme, if the issue persists, then there may be a conflict with specific plugin settings, server configuration, network interference, or even WordPress itself (although rare, in my experience). In this case, further testing is required in order to find (and hopefully resolve) the issue.

This is where ground-up testing can be useful. Instead of trying to reverse-engineer your entire current site, you can start from scratch using the ground-up technique, which gives you a “clean slate” that eliminates all other variables. Let’s take a look..

Troubleshooting from the ground up

Ground-up testing is basically:

Set up a new WordPress installation, leave everything at the defaults (e.g., plugins, theme, and settings), and then install the plugin or theme that you want to troubleshoot. This enables you to verify that the plugin works normally, without interference from any other plugins, theme, or settings.

Pros of ground-up testing:

• Gives you a clean slate to work with
• Does not interfere with your other/original site
• Provides a baseline where the plugin works correctly

Cons of ground-up testing:

• Takes more time to set up another WP install
• May require transferring of plugin license(s)

Let’s look at a quick example..

Example

For example, say you have a plugin named “Super Duper”. It is not working correctly, and you suspect there is some conflict with one of your other plugins or theme. You want to find out why the issue is happening, and hopefully get it resolved. Before contacting the plugin provider, take some time to do some basic troubleshooting. Doing so will help the support team understand and provide help as quickly as possible.

Troubleshooting steps

To troubleshoot why the Super Duper plugin is not working using ground-up troubleshooting, follow these steps:

1. Set up a new WordPress installation
2. Leave the plugins, theme, and settings at default values
3. Install only the plugin (or theme) that is not working

After following these steps, you can verify that the plugin or theme you are testing works normally on default WordPress. This is your baseline: the plugin works on default WordPress. IF that is not the case, then you have found a bug with the plugin (or theme) itself. And should be reported to the plugin developer.

Otherwise, if the plugin is working properly on default WordPress, then the problem is not a bug with the plugin, but rather a bug with your particular setup, configuration, etc. So further testing is required..

Test your other plugins

Once you verify that the plugin is working properly on default WordPress, you can begin troubleshooting by installing and activating each of your other plugins, one at a time. You want to re-test the problematic plugin after adding each new plugin. At some point, as you are doing this, the issue will return, and you will know exactly which plugin is breaking things.

If you get through adding all of your other plugins, and the issue has not reappeared, the next step is to test your theme.

Test your theme

If you get through adding all of your other plugins without the issue reappearing, then move on to the theme. Try installing and activating whichever theme you are using on the other site and re-test the issue again. If the theme breaks things, then you have the information you need to either:

• Report the issue to both plugin and theme developers
• Troubleshoot within the theme itself (or hire someone to do it for you)

And of course, if you get to this point and the issue has not resurfaced, then yep you guessed it, more digging is required.

Beyond plugins and theme

If you get through testing each of your plugins and theme, and the issue does not return, then there must be something else — some other difference between your original WordPress installation and the test/default installation — that is causing the problem.

In this case, the next step is to figure out the specific differences between the two WordPress sites. For the sites to behave differently (i.e., one showing the issue and the other working normally), there must be some difference between them. Your job is to continue the troubleshooting process by eliminating variables until the issue returns.

Take-home message

The take-home message for this tutorial is that troubleshooting is something that literally anyone can do. It is a straightforward, proven process that helps millions of people diagnose problems every day. And more importantly, a bit of troubleshooting provides valuable information that can help the plugin or theme provider to understand and hopefully resolve any issue.

Remember, the people who develop your WordPress plugins and themes love to help you, but they are only human. They do not possess a crystal ball or Palantír that magically reveals to them exactly what is happening on any given site.

Seriously none of us have anything like that.

We have no idea what’s happening on your site unless you tell us. So by doing some basic troubleshooting, you can provide the developer precise information, increase the chance of getting the issue resolved quickly, and benefit from better understanding of your own website.

Going further..

For a more in-depth troubleshooting tutorial, check out my post at Perishable Press: The Art of Troubleshooting WordPress. That goes into much more depth, plus provides all sorts of tips and tricks, etc.

Thanks for reading and happy troubleshooting.