Troubleshooting WordPress Like a Sniper

I decided reign in the new year with this post as a follow up from my last epically long blog post, How to Update WordPress Without All Hell Breaking Loose.

I’m sure my previous post might’ve been useful for those familiar with the WordPress directories and their innards, but what about those who aren’t? Browser cache? Config file? Browser console? What is all this dev lingo and how does any of this help the average joe with troubleshooting WordPress?

And so, I’m recycling some pieces from my last post so I can go over general steps for troubleshooting WordPress again in more depth. No geek speak, no dev lingo, just learning how to troubleshoot like a true marksman! Hopefully by the time we’re done, you’ll come out of this post feeling less like a blind troubleshooter and more like a sniper who hits the mark every time. Let’s get started…

How to know when WordPress is broken.

First of all, how do you know when something’s off about your site, and how will this help you? Knowing the nature of the problem will help you narrow down what steps you have to take to resolve it. If you have a general gist of what might be wrong, you can save time by making the right troubleshooting steps. The only time you really have to go through an entire checklist of steps is if you really have no blinking idea what the problem could be.

WordPress can break in one of multiple ways. This usually this consists of:

• Broken links: Links that once took you somewhere now take you to a 404 page or “page not found” page.
• Broken images: Images are now missing and have that ugly broken images symbol in their place instead.
• Wonky looking design: When your formerly perfect and beautiful design suddenly shifts the wrong way, colors change, layout breaks and so on.
• Functionality misbehaving: Things that worked once before such as a drop down, a social feed, or even a popup are either behaving erratically or not doing what they should at all.
• The famous white screen of death: Where everything goes absolutely white. Looks like a completely blank screen. And in worst case scenario, it may even lock you out of your WordPress admin.

If one or more of these are happening, you can bet that your site needs some investigation.

What usually causes WordPress to break?

Unfortunately, this isn’t a simple answer. But some possibilities are:

• Bad code: This can be something as small as an accidental extra semi-colon, a div that wasn’t closed correctly or a CSS selector using !important somewhere it shouldn’t. These minor issues are usually easier to hunt down and resolve. Bigger code issues however, are not that simple. Examples of bigger issues would be code that doesn’t follow coding standards. This in itself isn’t always an issue, but by not following standards, there is a greater change that code hasn’t been written as cleanly as it should and also in danger of being outdated. There’s also a chance that this code wasn’t written with future-proofing in mind. What I mean by future-proofing is writing code to play nice with other plugins/themes or other versions of WordPress aside from the one it’s currently living on. To future-proof something is to create something with the future in mind, not just the present circumstances. Future-proofing is assuming the worst and making the proper preparation ahead of time just in case.
  

  An analogy of this would be a guy driving in his truck through the sweltering desert. Sure, he doesn’t expect his truck to break down, and he doesn’t expect to get lost. Hell, I’m sure he doesn’t expect to get robbed! But if he’s smart, he’ll keep survival tools within easy reach should something inconvenient happen during his trip. Flares, water, food – you get the gist.

  By having these tools every time he drives through the desert, he’s preparing for the future by imagining how to adapt to different scenarios whether they actually happen or not.

  Code should be written in the same way. Prepared and/or flexible enough to adapt when the unexpected happens. Unfortunately, we’re all only human. One can only predict so much and in defense of developers, some WordPress users try some pretty unconventional things. Bad code is usually the number one root of all evil. All it takes is one plugin ( for example ) to break an entire site. An example of this would be an issue I once saw on the WordPress Stack Exchange where “Junior” ( Let’s call him Junior) had two plugins he needed to activate. One plugin needed the other to work properly. Therefore Plugin B needed Plugin A to function. However, Junior activated Plugin B before activating Plugin A. Now depending on how well the plugin was written, one of two things should have happened at this point.

  1. What should have happened:

  If Plugin A exists, Plugin B, do your thang! Or else, if Plugin A doesn’t exist, Plugin B, throw an error letting Junior, our user, know that you need Plugin A to work instead of doing your “thang” without permission. This way things don’t break because we’re telling Junior what he needs for Plugin B to work properly.

  2. Here’s what happened instead:

  Plugin B looks for Plugin A. Plugin A doesn’t exist. Plugin B doesn’t know what to do now. Plugin B freaks out. The site breaks because Plugin B is on a rampage without anything to prevent it from doing so.

  Plugin B then caused code errors that ended up giving unfortunate Junior the white screen of death. There was no way of preventing Plugin B’s functionality ( it’s thang as I’ve been saying ) from happening since the plugin developer didn’t build it in a way that predicted that perhaps Junior might end up activating Plugin B without realizing he needed Plugin A first. Instead of stopping their plugin in the event that Plugin A wasn’t active and telling Junior where he went wrong, Junior is then confronted with the white screen of death. This is the point where Junior posted to the WordPress Stack Exchange because the white screen also locked him out of his dashboard, making him unable to de-activate Plugin B that was wreaking havoc on his site.

• Migrations: When moving a site from one place to another, whether it’s your computer to a live server ( aka on the web ) or even moving a site from one domain ( web address ) to another – this is another common source of WordPress woes. If the migration process, which is usually a range of steps, hasn’t gone 100% to a T, things can go wrong here.
• Upgrades: This is basically what I went over very thoroughly in my last post. Since your plugins, your theme, your WordPress version, your database, and your environment are all factors that can either make or break your site in an upgrade, this is another common source of WordPress catastrophes. The combination of these things working together can sometimes cause issues usually due to the first cause I listed – bad code.

Those three are the biggest sources of WordPress headaches that I’ve seen and experienced myself: Bad Code, Migrations, and Upgrades. Some other root causes could be permalink settings, missing files or directories, incorrectly installed or missing databases, a function from a parent theme overwriting your child function and the list goes on.

How Do We Fix It?

So far, we’ve gone over symptoms of a broken site, and we’ve also gone over the most common sources of a site breaking. By knowing those two things, we can narrow down where and how to troubleshoot, or rather, trouble-snipe!

Front-end Troubleshooting Steps:

And by front-end, this means, the front-facing part of the site. The part of the site that all users see. The public face of your site. Not the admin/dashboard. So your homepage, about page, all those things that people see that has nothing to do with the configurations or your WordPress plugin management or your post content and so on – this is the front-end of your site.

If something looks weird here, this can be caused by a few things.

• CSS conflicts or mistakes: Meaning something in the stylesheets of your theme, child theme or a plugin could be interfering with your site. You can determine if this is the case by using your browser inspector to check if the styles on your site are applying to where they should be. Your browser inspector is a tool in your browser that allows you to look at the code to a site without needing to go into the files. How do you use this so-called browser inspector you ask? Check out this really cool article by Hope Connell, A Web Inspector Tutorial based on Google Chrome. Firefox’s inspector also works similarly. If you’re using IE… just give up.

  

  Anyway, maybe there’s a change in the CSS that’s supposed to be there and isn’t, or another stylesheet is overriding yours, or perhaps the selector you’re using needs to be more specific. A what? Check out what is a CSS selector if that confuses you. Either way, if the issue is CSS, the browser inspector is the tool you need to start resolving it.

• Missing Stylesheets: There could be a stylesheet failing to load. You can use your browser inspector to check this as well. There’s a “network” tab that will show a file path in red with a 404 error on it if your site can’t find the file. See below for an example of a typo causing the missing file:

  

  Confirm that all files are loaded correctly using either wp_enqueue_style or wp_enqueue_scripts. Also confirm that they’re loading in the correct order and if you’re using a child theme, you’re overriding correctly. Confused about child themes? Check out WordPress’ child theme resources.

• Javascript: Sometimes Javascript/JQuery errors can cause your site to appear wonky design wise. You can figure out if this is the case by using the browser inspector as well – except this time, there should be a tab or option somewhere called “console”. The console is usually where JS errors or missing file errors appear. An error usually looks something like below with red blaring text and an “x” icon:

  

  If you see these, then you’ll need to check on the right hand side of the error, it will usually tell you where the error is coming from. Still not sure how to do this? Take a gander at Chrome’s “Using the console” instructions or for more advanced tricks, Tree Houses’ “Mastering the Developer Tools“.

• Clear Browser Cache. Your browser keeps a history of a site unless you’ve set it not to. So sometimes what you’re seeing isn’t actually your site in it’s latest form, but a “cached” or saved version of it. This interferes with you seeing the latest changes so even if your CSS is fine and your JS is error free, you may be viewing a version of the site with errors. Clearing the cache ensures you’re seeing your site in it’s latest and greatest. Check out 15 Ways to Clear your Browser Cache. Also if you’re using a cache plugin, clear that as well. For sites on live servers, there may also be caches on there – for that, you may need to contact your hosting provider or a WordPress pro.

Back-end Troubleshooting Steps:

And by back-end, this is the opposite of front-end. This is your dashboard, your files, your configurations, your database, the parts of the site that average users do not have access to. If you get the white screen of death, plugins aren’t behaving as they should, your dashboard appears to be broken – these could be caused by back-end issues.

1. Your database credentials are wrong. If you’ve got the “Error establishing a database” screen, odds are there’s something up in your wp-config.php file or “config file” as some may call it. This is located in the root of your WordPress site. WPBeginner has a good article on how to fix the Error Establishing Database screen.
2. Core files need replacing or an upgrade didn’t complete the database update. If you’ve ever logged into your dashboard and seen this ( see below ) – then there are usually two fixes that work for me to resolve it.

   

   What a broken dashboard looks like – still not sure what causes it but my guess is something with the database…

   This is something I still see from time to time and no matter how often I see it elsewhere or experience it myself, it’s not clear to me how this problem happens. Anyway, when this does happen, I do one of two things.

   One: If this happens while you’re trying to upgrade a WordPress site, usually from a really old version to a newer one, sometimes things go wonky in the process and the database fails to update properly. Try logging out and back in, and seeing if it prompts you to update your database. If it does, then update and you should be good to go. You can also manually update this way if the prompt never shows up.

   Two: If this just happens and you have no idea how or why it’s happened, try replacing the wp-includes and wp-admin folder in the root of your WordPress site with fresh copies from the WordPress release archive. Basically you find your version of WordPress, download it, and copy those folders to replace your site’s.

   If the problem persists, check your site at a later time ( Seriously, this has worked for me where a dashboard that was broken mysteriously fixes itself – no idea why.) or find a WordPress pro for further assistance.

3. PHP Errors. Since WordPress is built on PHP, this is what usually causes the white screen of death and there are various ways to troubleshoot this. Usually troubleshooting starts by ruling out the theme, ruling out plugins, and turning on debug mode. Check my earlier post for a more detailed step by step of this process under “General Troubleshooting Steps”.
4. Broken images and Urls. This is usually from either missing directories, permalink settings or your htaccess file. These issues happen a lot during migrations or on servers where the user doesn’t have control over cache/permissions after they’ve made permalink changes. If the images are broken, check your theme files, confirm those folders and the images exist. If urls are broken after a migration they could be hardcoded in WordPress so you’ll have to manually change them. When I say hardcoded, I mean that the links were written out manually versus using something like PHP that will update the urls during the migration process. Here is an example of a hardcoded url:

   <a href="www.rachievee.com">Hardcoded RachieVee is bad!</a>

   And here’s an example of a url that would be dynamic ( future-proofed ) so even with migrations, it’s safe from being broken unless the destination is changed or removed. This examples uses the site_url function.

   <a href="<?php echo site_url(); ?>">Dynamic RachieVee is Better, Yay!</a>

   You can manually change hardcoded urls by finding them in your posts/pages or you can go into your database, export it, do a find and replace of the old url to the new url, and then re-import the database. I won’t go into too much detail on how to do that as I’m trying to keep this post as simple and as short as possible. You may also need to go into your theme files and update any hardcoded urls there if there are any. For more on permalinks and images, WordPress offers how to resolve when images and pretty permalinks don’t work.

When to Call in the WordPress Pros?

Usually it’s a good idea to try and resolve a problem on your own – sometimes it’s simpler than it first appears. It’s also a great learning experience in spite of the headache of going through it. There are cases though where I don’t recommend jumping in, or at the very least, stopping at a certain point to prevent further damage to your site or your sanity. These cases are:

• You’ve already tried to troubleshoot multiple times, even after taking  a break and returning to the problem in a calmer state and losing lives at this rate. I’d recommend finding a buddy that can help or posting your issue to WP Stack Exchange or the WordPress Support Forums.
• This is a client’s live site. If you’re panicking and don’t have the time to fix it before your client freaks out, revert any and all changes made. You should definitely have a copy on your own computer or a backup solution of some sort. If your client’s site only exists on a live server, now’s the time to think about making a local copy of the live site. A local copy is a copy of the site on your computer. When someone says local, they mean on their computer, not online/hosted on a server. Never troubleshoot directly on a live server unless the problem is only one that happens solely on the server. This itself can be a huge clue as to what the issue is if it’s only happening on that server versus another server or local copy.
• It’s on a hosting provider you don’t have any control over. If this is one of those “1-click install” sites and it’s suddenly broken, you may not have access to all the tools you need to troubleshoot such as a PHP error log, access to root files or server cache. You may have to contact your hosting provider for support.
• Anything database related if databases sound like foreign territory. The database is basically the organs of your site. Break something here without having a backup, and it may be impossible to recover. Better to be safe than sorry and get a pro to help out or at the very least, back up your database before tinkering.

Also check the Common WordPress Errors page for more troubleshooting tips. If the situation is dire, sometimes you can find the solution on your own before someone gets to you on a support site.

Becoming a Troubleshooting Sniper

In this insanely long post ( seriously, I need to write shorter ones ) I went over a few major points in your mission to go from blind troubleshooter to savvy trouble-sniper. These points were:

1. How to know when WordPress is Broken. We went over some symptoms of a site breaking such as broken images, weird design issues and the white screen of death.
2. What causes WordPress to break. The three main sources are bad code, migrations and upgrades.
3. How do we fix it? Based on what appears to be broken and the main/minor sources of what usually causes breakages, we can determine how to go about resolving the problem. Here we went over how to resolve front-end issues with tools like the browser inspector and the console. Then we went over back-end issues with solutions like checking the config file, replacing core files, and fixing your htaccess.
4. Finally we went over when it’s a good idea to back away and call for help. Sometimes a second pair of eyes is all you need to hit the mark.

We also went over demystifying some of that dev lingo. Here’s the list in no particular order:

• Browser Inspector
• The Console
• Browser Cache
• The “config” file – or rather, the wp-config.php file
• Front-end
• Back-end
• Future-proofing/Dynamic
• Local copy

If there are any other terms you think I should go over, leave me a comment! I’ll be happy to explain them. 🙂

And that’s it! I really meant for this to be shorter, but it didn’t end up that way. I hope that although long, this post helps to clear up some of the code monkey jargon and also saves you some unnecessary troubleshooting steps the next time you face an issue on your WordPress site. There are a lot more causes and solutions that I didn’t mention here as everyone’s case is unique. Instead, I went over some basics in the hopes that it will give all the troubleshooters out there the right artillery to get started.

Until next time, happy trouble-sniping!