A Guide to Debugging in WordPress with your Reptilian Brain
Since so many things can go wrong in a WordPress environment, it’s important to develop general WordPress bugfixing hunches.
Debugging code is a huge part of my job. It can also be quite scary, particularly in a WordPress environment, because of the sheer number of things that could go wrong. Uh oh, the client’s shop page isn’t listing properly. Maybe the theme is expecting the wrong WooCommerce version? Maybe WooCommerce is interacting badly with a third-party plugin? Or with something we dropped into
functions.php? Maybe we dropped bad markup into the page template itself? Maybe one of our CSS stylesheets is hiding the wrong types of elements?
Over a long time working with this problem, I’ve developed a set of general WordPress bugfixing hunches, which help me suspect the likely type of a bug, and then to poke at the problem until I find the source itself.
These hunches are a bit like having a second sense of smell, which I use to wander in the vaguely right direction until I find the carcass I’m looking for. I suspect they live down in my reptilian brain, the primitive part that regulates things like body temperature and snapping at food.
Today, I’d like to share these hunches with you! I hope these guidelines will start to help you develop your own instincts for better, quicker bugfixing in WordPress.
Caching is probably the most common cause of unexpected behavior in my work as a WordPress developer.
Caching is probably the most common cause of unexpected behavior in my work as a WordPress developer. Since “caching” is a blanket term for any time a technical process saves time by using stored data instead of fetching the data new again, there are a vast number of types of caching, and “WordPress caching” can mean a huge array of things. David covered these splendidly in a recent article, and that’s highly recommended reading.
But remember: today we’re reptiles. We don’t understand all the possible caching layers that may exist on the internet. Here’s how to cache-bust without knowing exactly what type of caching you may be dealing with.
When to Suspect Caching as the Issue
Suspect caching when you make a change and nothing seems to break, but your change doesn’t show up.
If you suspect caching as the problem, go through these steps, in this approximate order, until your problem disappears.
Hard-Refresh Browser Tab
On the misbehaving tab, hard-refresh with Ctrl+Shift+R (PC) or Cmd+Shift+R (Mac) to clear out issues with browser caching.
Open Page in New Browser
Hard-refreshing won’t solve some issues with cookies and the like. Keep a secondary web browser (either Chrome or Firefox) that is set to never record session information, and open your page in that environment.
Clear All Caches You Have Access To
You may be running a WordPress caching plugin; manually clear its entire cache.
Some hosts (such as our host, SiteGround) also operate independent caching layers; if the host doesn’t provide a plugin to manage these in WordPress, you must disable them through your hosting account. Call their support techs to figure out the specifics.
Change Internet Connections
Some kinds of caching, notably DNS caching, live at the level of your internet service provider (ISP). Particularly if you’re dealing with issues related to a newly purchased, created, changed, or reassigned domain name, you may need to actually change ISPs to see your changes—for example, by visiting your site through your phone’s data plan rather than your computer’s wireless connection.
WordPress Environment Debugging
WordPress—Core, themes, and plugins—might be “working” properly while still giving your users problems.
The WordPress environment refers to a very complex, very stateful combination of WordPress Core, themes, and plugins. All of these things might be “working” properly—not written with actual errors in the code—but still behaving badly from the standpoint of your and your users’ expectations.
When to Suspect the WordPress Environment as the Issue
Suspect WordPress environment issues when you’re managing a site rather than programming.
You should suspect issues with the WordPress environment when you’re managing a WordPress site—perhaps writing content, installing plugins, placing widgets and shortcodes—rather than “programming” directly, and something odd happens.
Working with WordPress Environment Issues
All manner of WordPress errors simply need a permalinks refresh. In particular, if a page unexpectedly 404s on you, this should be your first thought.
Simply navigate to “Settings>Permalinks” and click “Save Changes.” This will clear out old permalink associations and build ones that correspond to your site’s current state.
Test Site Both Logged in and Logged Out
WordPress may behave quite differently depending on whether you’re logged in or out For example, your site may serve cached versions of many resources only to users who view the site while logged-out—meaning that everything looks fine to you, but not to your actual users. Logged-out users may also be accidentally barred from accessing resources (such as pages) that you can access, and a number of other issues exist.
To test this issue, open your site in a second browser and navigate the site while logged in in one and logged out in the other. If the site works in one environment and not the other, then logged-in state is impacting your site’s behavior in an unexpected way. In particular, if your problem appears only on the logged-out site, it could be an unresolved caching issue.
Start Deactivating Plugins
A WordPress site’s plugins may introduce literally any third-party code into the site environment. This means that bad plugin code could break literally anything about your site.
Aim first for plugins that do lots of heavy plumbing to make a technical task available to non-developers.
If you’re seeing unexpected behavior, it’s never a bad idea to strip as many plugins as you can by bulk-deactivating them (no need to delete them) and checking if your problem persists. Aim first for plugins that do a lot of heavy plumbing in an attempt to make a technical task available to non-developers; plugins with names like “User Role and Permission Manager,” “Custom Nav Menu Manager,” and “Visual Page Builder” are likely suspects. Just about any plugin can cause problems, though, except maybe Akismet.
Be aware, of course, that deactivating your plugins will break your site in lots of other ways, so it’s best to avoid if possible on a live site.
Dive Into Theme and Plugin Settings
A lot of issues on a given WordPress site come down to theme and plugin configuration. For example, if your client wants to add a second payment method after PayPal, that’s definitely a job within the settings of your e-commerce plugin. If your client wants to put an image logo where the site title is, that’s likely a theme option in the WordPress Customizer.
If you can’t find a way to get a specific theme or plugin to work “as it should”—and if what you want seems reasonable and likely to be shared by other users—then dig deep into the documentation and look for a setting before you resort to other tools.
Your web server is where your entire WordPress site lives, and it controls all the ways in which your WordPress site interacts with the outside world. There’s quite a bit that can go wrong with this whole setup.
When to Suspect Server Issues
Server issues are severe, and usually manifest as “things not getting where they should.”
Server issues are severe, and usually manifest as “things not getting where they should.”
For example, if you or your users wake up one morning and can’t access your site at all, that’s likely a server issue. (You can be absolutely sure this is true if you start seeing things like
500 Error or
502 Error, which are ways a server tells you it’s broken.)
Other types of server configuration issues might include your site’s homepage redirecting to a page that doesn’t exist, your contact form failing to send emails to anyone, and your domain name pointing to the wrong version of your site. These are all ways that the server is sending things to the wrong places, or not at all.
Working with Server Issues
Every decent web host provides free tech support.
In a typical shared WordPress environment, you do have quite a bit of leverage to manage your server directly, through cPanel, your WordPress install’s
.htaccess file, and so on.
If you’re comfortable with these tools, that’s great, but my actual advice is to call your host. Every decent web host (the folks who let you put your site on their servers) provides free technical support. If you suspect that your site may have a server configuration issue, you should call your host as the absolute first step.
Browser and Device Issues
Different web browsers interpret the same website differently, as do different internet-capable devices. Getting everyone’s interpretation to match your goals for the site can create a lot of complexity.
When to Suspect Browser and Device Differences as the Issue
As Internet Explorer dies off, browser issues are quieting from a howl of despair to a steady whisper of concern.
Thankfully, the browsers that are widely popular today behave much more logically—and similarly—than was the case five or ten years ago. As Internet Explorer dies off, browser issues are quieting from a howl of despair to a steady whisper of concern. However, old and bad browsers do exist, and your site visitors may be using them. Suspect browser issues when a user complains of broken site layout or missing elements, and you can’t replicate the issue.
Mobile devices also introduce a huge range of complexity. Suspect these issues anytime someone views your site on anything other than a computer, if you haven’t paid close attention to the mobile experience.
Working with Browser and Device Issues
Again, browser issues are thankfully less and less prevalent, but if you do run into an issue with Firefox or Chrome (they exist), or if a significant proportion of your users are having broken experiences on old IE versions, you can likely identify a fix by describing the issue carefully in Google and navigating to a Stack Overflow result.
Responsive development—development for all web-capable devices—is primarily a front-end art which uses things like responsive grids and CSS3
@media queries. The literature is vast and well-established, so simply Googling “responsive development” should get you a long way.
Some bugs do develop because you’ve written an actual error into your code.
Some bugs do develop because you’ve written an actual error into your code. These errors manifest differently depending on which of WordPress’s four key technical languages is the issue.
When to Suspect Buggy Code as the Issue
When you’re writing code into a theme or plugin and the site stops behaving as you’d expect, you’ve got buggy code. Buggy code could also come from third-party themes, plugins, and other assets, so the following tools are good to inspect any issue that the above tools aren’t addressing.
PHP Debugging with
If you’re seeing a Whitescreen of Death—nothing on the page when you try to load it—then your site has a PHP error. Follow the instructions in our article on WSODs to enable WordPress’s
WP_DEBUG feature and find the file and line that’s causing the problem.
Other PHP errors may not WSOD your site but may cause other problems. It’s a very good idea to have
WP_DEBUG on while you develop on a site, as long as you’re not working on the live site. Do know that many “Warnings” that will show up can be safely ignored—they relate to deprecated ways of writing code that have nothing to do with you. “Fatal Errors” and the like are what you’re looking for if you suspect PHP errors.
JS Debugging with Console
console.log() function to print into the console any piece of data that you may have questions about, and compare that data’s expected properties with its real properties in the console.
HTML Debugging with Browser Inspector
In general, if things just start to look weird on your site, it’s an HTML or CSS issue. Bad HTML markup tends to lead to issues like missing elements on the page and styles that seem to bleed over where they don’t belong. For example, check out the following code:
<h4>PHP Debugging with <code>WP_DEBUG</code><h4>
And its effect on this article as I wrote it:
These types of bugs should be easy to identify as you browse the site, and fairly easy to diagnose by inspecting the markup using some combination of a browser inspector, “View Page Source,” and directly staring at the HTML markup in your post content and your theme’s PHP templates.
CSS Debugging with Inspect Element
Many display errors come from erroneous CSS rules—for example, badly written rules that apply to the wrong elements. I’ve written a detailed article on identifying and fixing CSS problems on a WordPress site that takes into account the potentially dozens of CSS stylesheets that may be generating overlapping style rules.
Thanks for Reading!
This article has worked to introduce you to some general ways of “sniffing out” bugs and errors in WordPress.
Having good hunches will save you a ton of time chasing dead ends, and will get you more quickly to the part where you find an elegant fix with that big mammalian brain that I’m sure you have. I’d love to hear your own hunches below!
Image credit: Sergey G