How to troubleshoot a WordPress site using Plugin Detective

Posted on September 5, 2019

When a feature stops working on your WordPress website, minor panic can set in. If yours is one of the approximately 40% (as of this article’s publish date) of websites that’s running WordPress 5.2 or above, you’ve probably received an email entitled, “Your Site is Experiencing a Technical Issue”, and you’re off to quickly fix the problem. But, what if you’re managing a website below version 5.2 or didn’t receive the snazzy new error email? A difficult-to-troubleshoot error can ruin an entire afternoon of productivity (and sales) attempting to find the issue and fix the site. 

Here’s how to troubleshoot a WordPress website prior to WordPress 5.2 (spoiler: not too efficient)

1. Disable all of the plugins on your website.
2. Open a second tab with the front-end of your website and ready the reload button.
3. Reenable plugins one by one as you refresh the front-end of your website.
4. Find the plugin responsible for the issues, and fix accordingly.

For a long time, this has been the common advice on how to troubleshoot a WordPress site prior to WP 5.2. While not technically wrong, this process can be time consuming and arduous at a moment when speed and accuracy matter. In 2018 at WordCamp Orange County, WordPress pros Natalie MacLees and Nathan Tyler presented a new spin on an old method of troubleshooting WordPress websites.

How to troubleshoot a WordPress site the efficient way

Natalie and Nathan dug deep into their classic programming knowledge and created a plugin that automates the plugin enable/disable process using a binary search. The plugin is called Plugin Detective and it finds broken plugins in a fraction of the time that it’d take the traditional method. Here’s how it works:

1. Plugin detective disables half of the plugins.
2. If the problem persists, the plugin re-enables the first half, and disables the second half.
3. If the problem is fixed, the plugin begins the same process on the new half, and continues until the offending plugin is determined.

Because the plugin uses a binary search, with every iteration, half of the plugins are ruled out. On a site with dozens of active plugins, this method saves a lot of time.

Putting Plugin Detective to the test

In theory Plugin Detective is a great idea, but I wanted to test out how it works on a real site. I installed a test site with sixteen active plugins, and intentionally put a typo in one of the plugin files to render the site inoperable.

The Plugin Detective (named Otto) started by asking if there were any required plugins that needed to be left on for the site to load. After all, there’s no sense disabling a key plugin and causing a different issue. I told Otto I didn’t have any required plugins on my site, and he started by disabling everything and asking me if the issue was fixed. (If the error was still happening, that meant that the cause of the error was probably something else, like mu-plugins or the theme.) Since my issue was fixed, Otto knew that one of the plugins was to blame.

The plugin ran through the list, activating or deactivating half of the list each time and asking me after each pass if the issue was resolved. Overall, it took seven passes for the Plugin Detective to determine which plugin was broken, and took less than a minute of elapsed time. Otto was also able to deactivate the offending plugin for me, so I didn’t have to mess around with (S)FTP or the database to manually disable it.

How to troubleshoot without access to wp-admin

The plugin worked really well, but I started to think, “what are the chances that the site I’m trying to troubleshoot has this plugin installed?” or, “what happens if I can’t get into the backend at all because of a white screen?”. Well, Natalie and Nathan must have had those same thoughts when they created Plugin Detective. If the plugin isn’t already installed on the broken site, it’s straightforward to get Plugin Detective up and running:

1. Manually copy the unzipped plugin folder over to /wp-content/plugins
2. Go to YOURSITE.COM/wp-content/plugins/plugin-detective/troubleshoot (which will load even if the site won’t load)
3. Log in with a valid WordPress administrator account
4. Say hi to Detective Otto!

Final thoughts on Plugin Detective

The ability to quickly and easily track down a plugin conflict on a white-screening site is impressive, and overall the Plugin Detective is an amazing plugin. Natalie and Nathan have really re-written the guide on how to troubleshoot a WordPress site using Plugin Detective, and we’ve quickly added the plugin to our troubleshooting toolkit for sites on older WordPress versions.