Troubleshooting: How to be prepared when things go wrong

in WordPress Tutorials

I’ve seen trouble. Perhaps I attract it. In order to take gambles you have to have a contingency plan. Han Solo had smuggling compartments. Even though he never thought he’d be smuggling himself it was a great thing to have when the time came! You need to adopt a Han Solo like approach by having what you need and the adaptability to conform to the current situation.

If you are running a WordPress site for a client, taking risks with plugins, theme changes and so forth probably isn’t a smart move. You will want to take a few steps before you run into trouble. The first is to have a reasonable expectation that your change (update, new plugin, etc.) will produce a desired result. The second is, when confronted with a problem, you are able to isolate and iterate until the problem’s root cause is found. The worst kinds of trouble that need shooting are the mysterious ones where suddenly something broke. Those used to drive me crazy. They don’t anymore. I am never more than a step or two behind most problems. That is because I follow the following guidelines.

The Power of Intelligence

Let no one question the power that intelligence wields. If you are driving down the road and a fault in your car’s hood causes it to open and obscures your view, your intelligence of what is on the road ahead of you then you will know the value of good intelligence. The last information you got through the window is rapidly aging and going out of date. The velocity of the car at the point of the mishap is critical because the faster you are going the less time you have to make a good decision. You could stomp on the brakes but who is behind you and how close are they? You don’t want to avoid an accident to the front only to get a freight truck welded to your back.

The same goes for your website – you want as much information available to begin with. The reason I mention this is because it is possible that you could make a change that, for example, renders your dashboard inoperable. This is the equivalent of losing visibility from your windshield at highway speed. In some circles it is referred to as a “high sphincter factor moment”; or in plain English, a moment with a high magnitude of undesirable aspects.

Valuable intelligence here would be a list of changes in chronological order, log files and access logs. Also note if any changes have been made to your browser and always have the ability to bring up a browser with no active plugins. Most likely you got locked out of your WordPress Dashboard by one of the last changes you made. Things that can do this are widgets that either are not compatible with your current WordPress, Theme or conflict with another plugin. A theme that is not compatible with the latest version of WordPress can also cause this. Sometimes your extensions get abandoned by the developers and they stop working as WordPress gets updated.

Keep a log of what your changes are. It’s not a lot of work to get started and once you’ve got it going it will become useful to you in the event of an emergency. Know where your log files are. WordPress, your web server, your OS can all produce log files. Know how to find them and open them. Look for them now and keep a journal entry of their paths. This can save you a lot of time and effort when things are not working! Finally keep up to date on what changes are going in. If a plugin has an update, read the description of the changes. Sometimes they tell you important things such as known issues, actions you must take and warnings about appearance changes. I’ve had updates to plugins surprise me because the plugin no longer seemed to be on the site – but reading the change log I found I needed to redo some settings or other easy tasks.

The Power of Isolation

Superman had his Fortress of Solitude and you need one too. No, not an arctic getaway, but a place where you can safely test things and do crazy experiments. I’ve seen some people set up their sites on hosting providers and then do all development against the host servers. I don’t approve. In fact I think this is not only the slowest way to do this kind or work, the risks are insane – and that is coming from a lifelong risk taker. (Trust me on this; my Mother hates to hear my vacation stories. They often contain references to encounters with dangerous fauna and measurements of the exact capabilities of the rental car.)

When I mention isolation as a concept I mean two things. The first is a division between development and production. I sometimes refer to this as loops – there was always a development loop and a production loop. They are totally separate environments. When I worked for major corporations we also had a testing loop where code was migrated to from development. Code migrated to production came only from the testing loop. Most WordPress development teams are too small to care to have a testing loop. If your business contains various products and separate groups then a testing loop is a good idea. Certainly a lone programmer really doesn’t need a testing loop but should definitely have a development loop.

On my development machine I have a simple stack. I use the XAMPP stack but there are many others to choose from. The XAMPP stack has the advantage of very easy installation, no security and works on Linux, Windows, Mac and Solaris. XAMPP is free. XAMPP works on your USB drive – even the little thumb sized ones. I have a mirror of my installation configuration on my dev loop. I don’t bother with having the same blog entries on my dev loop as what are in production. I created several entries with the help of Ipsum Lorem generators. If you look you can find some pretty fun ones to play with.

A quick note on the lack of security in XAMPP. This is a good thing. When developing and troubleshooting, security adds another layer of complexity and possible source of error. You want the simplest environment possible when both developing and troubleshooting

If I see a plugin I am interested in, I load it on my development loop first. I’m set up to recover any programming I’ve done with my version control software (I use SVN but CVS, Git and others are also useful). I can test the plugin out and experiment with how it is to be used safely on this loop. If it messes up I can reset my installation easily without causing downtime on my production loop. Clients like that sort of thing. Isolating your production loop from your development loop and trying new things in development first before pushing them live to the web is just smart. Setting up WordPress locally for experimentation frees you to try all sorts of things you wouldn’t think of doing on your web facing blog.

The other concept of isolation is much more introspective. Instead of isolating your site from your development this form of troubleshooting involves looking more carefully at your installation and looking for the source of the trouble.

Your list of changes and updates will form your prime suspects. Your error logs and displayed error messages are very useful in helping to isolate the root cause. Just remember that just because the error logs point at widget XYZ failing, it could be because of some other component that has caused it to fail. If that widget did not change recently and has been working fine for a while then your suspicion should be on other components. Ask yourself, why would this fail? What would cause this to fail in this way? What new elements affect the things needed to make it fail?

When you have a repeatable error one trick that is useful is simply turning individual plugins off, testing for the error and then, if you don’t see it, turn the plugin back on and turn off the next one. Being methodical and scientific is the best way to dismiss culprits. If all else fails switch to a default template. Also, never just accept a problem. While you may feel you can use a workaround you may be just setting yourself up for further future instability. If something doesn’t work well and play nicely with the other components then get rid of it.

All Plugins go to Heaven

Recently I had a potential user of my site write me saying they could not register with my site. I tried it myself and found that the 3.x WordPress upgrade caused trouble for an anti-spam user plugin I was using. I went to the plugin’s homepage. When I got the 404 error message I deleted the plugin and found a replacement. After some testing I determined it was compatible with my configuration and now that is the one I use and support.

Not every plugin is written by a genius whose passion is to keep that plugin fresh and functional as WordPress develops. Sometimes the plugin just dies of neglect and changing times. All plugins have a lifespan and unless rejuvenated with updates they can’t be expected to keep pace. Over that lifespan you will install the plugin, keep it up to date with updates and eventually replace the plugin when it is no longer functionally compatible with the platform or your other plugins or another plugin comes to light that does what it did only better.

With a Little Help from your Friends

Get involved with the forums at WordPress. By involved I mean reading them and getting in on the conversations there. You will often hear of trouble long before you encounter it. This can make your life easier and prevent the need to troubleshoot. You will also come across other people who have had the same problem you might be experiencing now. There are also forums for PHP, for specific plugins and other related topics. Go to meetings in your area of other users of WordPress. If you live in a remote place you may have some trouble but if you have access to a college or city you may be in luck. I used to find my local WordPress Meetup. It has been very rewarding.  If you can’t find a WordPress specific meetup it is usually not hard to find web development groups. My meeting other people and attending discussions you will network and come in contact with people who can help you expand your knowledge, make friends with and get your own questions answered.

Final Words

This article hasn’t been about how to fix your specific problem. It is about preparing yourself to deal with trouble. Gathering intelligence, isolating production and isolating error causing components, plugin lifecyle and finally networking are the best ways you can prepare to take on any problem and without the absolute need to bear arms! Troubleshooting is like chasing down a fugitive. They don’t just run into your open arms. They run, like Dr. Richard Kimball and they run like hell. Any system of any complexity can mask a problem if it is a cascade of failures. You see the final failure but what were the ones before it that were the real cause? It’s like the guy that owes you $20 and never seems to be around. If you go poking around, asking friends and family you’ll find him. Like the deadbeat, any problem with WordPress is going to leave a trail. If you have done some footwork ahead of time and stick to being methodical then you can figure it out.