How to Troubleshoot WordPress

This guest post was written by Neil Matthews, a WordPress consultant at WPDude.

Over the years, I’ve developed a troubleshooting methodology while working with my WordPress technical support clients. My methodology helps to solve the majority of WordPress crashed sites I’ve come across, and I wanted to share it with you, the good readers of ProBlogger.

I cannot claim that I invented the process, but I have brought together a number of useful tips from the WP community and combined them to create a repeatable and verifiable way to isolate and troubleshoot WordPress problems.

The process

This methodology isolates the various layers of a WordPress site one at a time, tests a layer by removing its component parts, and then, if the problem still exists, moves down to test the next layer.

Once you have isolated the problematic component, you can remove it from your site and troubleshoot the problem itself.

I recommend doing this in a slow and ordered manner, incrementally testing each layer as you go. Look at a layer, disable all of the components, and slowly restart them to find out where the problem lies.

The layers

I like to divide WordPress into four layers:

plugins
theme
WordPress core
database.

This methodology looks at the first three layers only.

What can this process fix?

This methodology can be used to fix a variety of WordPress issues including, bit not limited to:

the dreaded “white screen of death” where all you can see is a white screen and nothing else
“Header Already Sent” errors
“Fatal Plugin” errors
“Out of Memory” errors
…many other WordPress problems, too.

Back up first

Even if your site has crashed, it’s important to stop, take a moment, and back up your site as it is now. You are about to embark on a journey which will make a lot of changes to your site. Taking a backup of the site as it stands means you can fall back to your starting position if you need to, without making the situation any worse.

Troubleshooting plugins

I always start at the plugin layer when I’m troubleshooting a WordPress problem. In my experience, about 80-90% of system crashes are caused by plugin issues. This is because there are so many plugins (sometimes of questionable coding quality) available to WordPress site owners. Combining these plugins with other plugins, themes, and WordPress itself creates an untested mix that can very easily crash your site.

This is how I troubleshoot plugins:

Disable all plugins.
Has the problem gone? If it has, you have an issue at the plugin layer, if not, move down to next layer the theme.
Re-activate plugins one at a time.
Test your site after each reactivation. Has the problem returned? If so, you have now found the suspect plugin: go to point 5. If not, rinse and repeat from point 3.
Disable that plugin.
Re-activate the other plugins to ensure you don’t have multiple plugin problems.
If the problem is still cleared, you have isolated and remove the problem. Go to the Getting Support section below.

Sometimes plugins cause such a problem that when you try to log into the dashboard to disable them, all you get is the same error message. If you cannot log into the dashboard, all is not lost: I have a work-around for you.

What you need to do is connect to your site via FTP and navigate to the wp-content folder. If you rename the plugins directory, to plugins_temp for example, WordPress no longer knows where the plugin files are, and stops running them. Now if you try to log in to the site, you’ll find that the issue has probably gone.

If you then proceed to the Plugins section in your Dashboard, you will see an error message that the plugin files cannot be found and have been disabled. Rename plugins_temp and you plugin files will be available again. Now, incrementally start from point 2 above to see which one caused the problem.

Troubleshooting themes

Once you have tested the plugins to rule them out, you need to move down a layer to the theme. This is how I troubleshoot themes:

Disable the current theme.
Activate a default theme such as Twenty ten.
Test. If the problem has gone, you know the theme is causing issues. If not, move down to the WordPress core layer.
Re-activate all of the plugins individually to make sure there is not a composite problem. If the problem doesn’t recur, you’ve isolated the theme as the problem area.

Next, I’d try to rule out any changes I’d made to the theme by removing any code I had recently added. If I have updated the theme, I’d roll back to a previous version. If I have just added a new widget, I’d try to back this out. As you can see, the process is all about back-tracking methodically so you can repair the issue.

Again, if you cannot log into the dashboard there is a work-around. Connect to your site via FTP, and navigate to the wp-content/themes directory. If you now rename your currently live theme directory to themdir_temp for example, WordPress won’t know where the theme files are. All you’ll see at the front end is a white screen, but the dashboard will be available. Go to point 2 above and activate a default theme. Remember to change the name of themedir_temp back to themedir to help troubleshooting.

Troubleshooting WordPress Core Files

The last layer to check are your WordPress core files. This is the last layer because it is the least problematic, but I have seen incidents where files have become corrupt, stopping WordPress from working correctly. The easiest way to troubleshoot WordPress core files is to re-install a clean copy.

This is my process for troubleshooting WordPress core files:

Download a clean version of WordPress from http://wordpress.org/download/.
Connect to your site via FTP.
Rename wp-admin and wp-includes to ensure you are uploading clean copies of these directories.
Back up wp-config.php just in case. This files holds your database connection details (amongst other things).
Upload your clean version of WordPress.
Test. Is your issue fixed? If so, you have isolated the problem at WordPress core. If not, it’s time to call in the experts.
Re-activate your theme and test it.
Re-activate your plugins and test them.

Fixing the component

At this point, you have hopefully isolated the component of your site that was causing issues. So what do you do now? Here are your options:

Visit the plugin or theme developers’ site and check to see if they have a support forum to search or request support from. Any developer worth his or her salt will be only too happy to provide support, and premium plugins and themes should provide top-class support as part of your fee. Remember to be nice to them if it’s a free theme or plugin and they don’t reply in five minutes.
Find a replacement for the plugin or theme. There is usually more than one implementation of a plugin, so if you can, swap out the problematic plugin with another one.
Request some support from http://wordpress.org/support/. This is excellent for core WordPress problems, and you will often find forums for individual plugins there, too.
Set the social media monster to work on your problem. Sometimes it’s as easy as sending out a tweet to your network to find a solution to the problem.
Get the pros in—hire a WordPress technical support team or consultant to solve your problem.

Wrap up

I use this methodology on a daily basis—it’s proven in the field on crashed sites. The key is to methodically work through the layers, eliminating as you go, until you find the root cause. Then, fix that issue. Remember to constantly test, though, because sometimes there are composite problems with multiple plugins, or the theme and a plugin.

Do you have any WordPress bug horror stories you can share? Who solves your site’s bugs and problems—is it you?

Neil provides WordPress technical support services at WPDude.com. He has also created a mini video course on this methodology over at wptroubleshooting.com.