Facebook Pixel
Join our Facebook Community

How to Troubleshoot WordPress

Posted By Guest Blogger 9th of February 2011 Blogging Tools and Services 0 Comments

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:

  1. Disable all plugins.
  2. Has the problem gone? If it has, you have an issue at the plugin layer, if not, move down to next layer the theme.
  3. Re-activate plugins one at a time.
  4. 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.
  5. Disable that plugin.
  6. Re-activate the other plugins to ensure you don’t have multiple plugin problems.
  7. 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:

  1. Disable the current theme.
  2. Activate a default theme such as Twenty ten.
  3. Test. If the problem has gone, you know the theme is causing issues. If not, move down to the WordPress core layer.
  4. 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:

  1. Download a clean version of WordPress from http://wordpress.org/download/.
  2. Connect to your site via FTP.
  3. Rename wp-admin and wp-includes to ensure you are uploading clean copies of these directories.
  4. Back up wp-config.php just in case. This files holds your database connection details (amongst other things).
  5. Upload your clean version of WordPress.
  6. 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.
  7. Re-activate your theme and test it.
  8. 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.

About Guest Blogger
This post was written by a guest contributor. Please see their details in the post above.
  1. Awesome!Thanks Neil for giving me some valuable tips.

  2. Neil,
    Interesting stuff although over my head. I have had several issues which ended up being plugin related. Like you said, I just had to deactivate them and reactivate them 1 by 1.

    This will be a good resource for the future. Thanks

  3. I like this method. I am one who usually asks for help because I am no genius when it comes to technical issues but this seems like a very logical way of dealing with problems. I haven´t had many problems with my blog (touch wood) but the problems i have had have been because of plugins so i have to agree with you on that point.

  4. Sometimes plug-ins don’t “play nice” together either – that’s a bit harder to troubleshoot.

    I also found it’s easier to troubleshoot on FireFox, an add-on such as “Firebug” is very helpful as well as the error console (Ctrl+Shit+J) . If the problem is a JavaScript issue you can very easily track it to the plug-in at fault with a bit of common sense.

  5. Awesome compilation! It’s frustrating when things go wrong, oftenly, the plugins :)

  6. Thanks for sharing these awesome and very useful tips Neil.

  7. Good stuff. One thing I would say about disabling plugins is that you may still need to go and edit the theme files to remove any code that references them, otherwise you could still face errors.

    As an example (not troubleshooting related, but makes the point) sometimes I’ve copied a theme from one blog to another, without moving the plugins across, and then received PHP errors (or possibly the ‘white screen’, which in this case is nearly always caused by PHP errors.)

    While this does mix up testing and fixing layer 1 and 2 issues somewhat, it’s important to note. However, I’ve not tried renaming the plugin folder before.

    Also, when it comes to testing PHP stuff, it can be worthwhile turning on error reporting. Whilst this should always be switched off on live/production servers, it can be invaluable in a testing environment as you’ll get the PHP error messages right there in your browser window with a pretty good explanation of what the problem is (well, at least, what it was that caused the script to fail — might not always be the root cause).

  8. romany says: 02/09/2011 at 8:55 am

    Thanks Neil. So often I’ve rushed in at the first sign of a glitch and compounded one problem onto another – your article will be a great resource whenever I’m tempted to imitate a headless chicken.

  9. A trick I first used in the old days of Mac OS 7 and control panels.

    Rather than work through one at a time. Split into halves, turn one half off, test, if no change turn back on and then the other half off and test again. If you get a fail with one of the halves repeat the process but just with the failing half, and so forth.

    This is a process that works for testing many things and if there are large quantities involved it can save time.

    OS 7 used to run with many c-panels. WordPress again can get very plugin heavy.

    But before this, don’t be afraid to go with your intuition, when did the fault start, what had you done around that time.

    Extremely useful article, thanks.

    • Had to laugh when I read that Andrew because I remember having to do the same thing. And you’re right, it’s a faster and more efficient way to check for plugin errors.

  10. Great post Neil. Dislike it when things don’t work.

  11. Thank you for this list of tips. I have had trouble with a plugin. It slowed everything down. When I made a post it took a long time – more than 5 minutes – to publish it and refresh the screen. This lasted for about a week. Finally after trying everything I could think of, I started deleting plugins. I deleted the most recent plugin and Bingo- That one was causing the whole problem.

  12. This wordpress troubleshooting guide is really awesome! I knew how to approach crashes by disabling plugins but didn’t know that some crashes may require FTP access to the files. As for themes, I’d stick to Twenty Ten wordpress default for now on my Work from Home Singapore blog since it is really stable.

  13. Excellent range of fault isolation steps for new blogger like me.
    Thanks, this is great post. :-)

  14. I am so glad to come across this post. I have been doing some minor WP consulting for bloggers and this is a great way to troubleshoot issues. Thanks for sharing!
    Being productive in stressful times

  15. usually i do an upgrade when plugin got broken

  16. Thanks for the tips, now i’m using blogger but many posting said that wordpress is better than blogger, so i want to migrate to wordpress

  17. The ‘headers have already been sent error’ normally occurs when you’ve installed the tweet button- at least that’s my case. I don’t know if anyone here is experiencing the same- of course if you are using WP :)

  18. Thanks for the tips…I’ll keep this in my starred folder, just in case…

  19. @Andy Merrett Good point, if you have coded your theme without testing to see if a plugin is active you may introduce new issues, but moving down and removing the theme should highlight this.

    @Andrew Butler I’m showing my age now, but you mean like coding a bubble sort to quickly find which half has the problem and then zoning in on that, yes that would speed things up, the trouble I have found is that you sometimes miss problems when there are multiple problematic plugins.

    Something I may have missed in my post to speed up troubleshooting is to read the error, it usually tells you where the problem lies

    thanks for you feedback on the post


    • Yes it did occur to me at the time to flag that possibility up, but in truth WP is pretty solid and unless you are going through a huge amount of change and development it’s fairly unlikely to happen. Famous last words : )

  20. Thank,s Neil Matthews for this information.
    I was facing some problem with my blog .some times posts looks ugly,ads not working,
    And most Links not works after updation of new version of wordprss.
    Now I have solve my problem and know this tip

  21. I so can relate especially with plugin errors. Mine was so strange once I could not login into the site at all..I wrote a post once I figured it out. Instead if changing the plugin directory, I delete the new plugin through file manager via control panel. The key is to always check when adding each plugin. Thank you, I love WordPress.

  22. Excellent article. I use the same process, however I don’t know that I could have explained it so well.

    I would stress using the WordPress forum as a resource. If I’m stuck I can find the answer there 90% of the time.

  23. Very good tips for me to start up again! Thanks

  24. Thank you for this. Deactivating all the plugins then reactivating them one by one is obvious now you’ve pointed it out – genius!

  25. Thank you for this amazing tips actually these tips are very valueble to who face a troubleshoot and problems in wordpress – like me of course – I will keep it in my PC thanks

    • Hi, I love WP, but today it decided to not see my u/name (even though it let me in this morning). It says my u/name is unregistered, even though I have had a website for 6 months. Who can I talk to at WP to reactivate my u/name? Thank you, Jane

  26. I have had themes and plugins interfere with various functionality like the comment system to the feed system, so it is always good to disable all plugins or switch to default plain theme to rule out theme issues. Also whenever plugins are updated be sure to test out functionality, more than one time a “comment form” plugin was updated and then I wasn’t getting any form submissions because something had broke, I could have lost dozens of potential clients as a result.

  27. Good stuff here. I have hosting at godaddy and it’s so confusing for someone who is new to wordpress. I think I’ve deleted themes now several times over and lost a lot of information. I’ve also done upgrades that have completely wiped out themes that I put a lot of work into. Sooner or later I’ll figure WordPress out but I have the impression it’s one of those applications that you just have to play with from time to time and learn the hard way when you make mistakes. I’m happy when I find websites such as this one with practical information that I can use.

  28. Memet says: 04/23/2011 at 9:37 pm


    Looking to get an error fixed in WordPress. It’s a cross between white screen and Parse error: syntax error, unexpected T_ENDWHILE, anyone can help me please?

A Practical Podcast… to Help You Build a Better Blog

The ProBlogger Podcast

A Practical Podcast…