Troubleshooting WordPress Issues

When something goes wrong on your WordPress site, how do you react? Do you freak out, or have a mini panic attack? Don’t worry, that’s a fairly typical reaction from the normal WordPress user ;) With this post I’d like to change the way you look at and react to WordPress problems :)

With WordPress, as with many things in life, we learn a lot when things aren’t going smoothly; learning to deal with technical problems pushes us out of our comfort zone and forces us to develop new skills and a deeper understanding.

Much of what I’ve learned in WordPress over the years has happened through things going wrong and me having to figure out how to fix it. Every time you face a problem and learn how to deal with it, your confidence is boosted and your problem-solving toolkit, and resilience, expands. The next time an issue crops up you are better equipped to handle it and you feel less panic.

“Do not learn how to react.
Learn to how respond.”

When faced with an error or an unexpected problem, a lot of people have a knee-jerk reaction. They might angrily call their hosting company, post a frantic message in a Facebook group, or submit an anxious support ticket. Usually the knee-jerk reaction isn’t well thought-out and doesn’t get you the best or fastest help, and it negatively impacts other people when you push your panic onto them.

Instead, I want to give you some tools and processes so you are better equipped to have a thoughtful response. Whether or not you end up fully fixing the problem, you will be able to:

• gather useful information to get better, faster help
• get your site back up and running
• identify the source of the issue

While WordPress itself is very stable, almost nobody runs WordPress with a default theme and no plugins on a rock-solid host!  In reality there are a lot of factors that can intervene, including:

• plugins
• themes
• hosting
• caching
• operator error (i.e. you!)

When faced with a problem, we have to detangle all these elements and use a process of elimination to find the issue.

First….Do a Sanity Check

This means making sure the problem really exists and is persistent and reproducible. You can usually do this with two easy steps:

1. Turn off, or clear any caching layer – that could be a caching plugin, caching from your host  or your CDN.
2. Then check another browser. Some issues can be solved simply by clearing your browser cache. If you try another browser or another computer and the problem isn’t there, it means it’s specific to your browser, so clear it: http://www.refreshyourcache.com/

The Problem Is Real!

OK, so the problem is persistent. If you remember what your last steps were, try to reverse them. Did you just add some code to functions.php? Did you install a plugin?

In reality most people do multiple things at once – updating multiple plugins etc and don’t really have an idea of how to backtrack. So this is where the real troubleshooting begins….

Is the Problem Plugin-Related?

We’re going to use a process of elimination. We’ll start by checking to see if it’s a problem related to plugins.

This is easy to do. Simply deactivate all of your plugins and see if the problem resolves [click for animated gif]:

Did the problem resolve? Yes? Great, we know it’s caused by a plugin.

Which one? To find out, turn your plugins back on, one-by-one, and check your site each time to see which one triggers the problem.

Alternatively, if you have an inkling of which plugin you think might be the culprit, you can take the opposite approach and turn off plugins one-by-one and see if you can find the issue that way.

But, I can’t even access my WordPress admin area, how can I turn off the plugins?!

No access, no problem!

In some cases, an error can take your site down, preventing you from even logging in. But that’s OK! No need to freak out, even if faced with this situation :)

For this step you’ll need either cPanel or FTP access. If you’ve never touched files on the server this way, I recommend you check out my post How To Go Beyond WordPress Basics since it goes over how to do this.

Once you have gained access, navigate to wp-content/plugins and rename the plugins folder.
I usually use: off.plugins but you can use anything you want. Click image below for an animated gif:

Now check your site – can you access your admin area?

If yes, great, it means the issue is caused by one of your plugins. After you login, your plugins screen will show a lot of red notices at the top:

Don’t worry, it’s normal. WordPress can’t find the plugin folder because we changed the name, so it deactivated the plugins, this is what we wanted.

So now we know it was a plugin problem. We can start activating plugins one by one to see which is the issue. To do that, first rename off.plugins to plugins again, your plugins will simply appear as deactivated in your dashboard and you will be able to control them from the plugins screen as normal (and the red notices will disappear).

So at this point you have identified the specific plugin causing problems. Now what?

The next step is likely one of two things:
1. If there is an update available for the problematic plugin, update it! The issue could be an incompatibility with the latest version of WordPress for example, which has been addressed in an update.

2. However, if you just updated, and that was the source of the issue, it could be a bug, or an incompatibility.

In this case, WP Rollback comes to the rescue!

WP Rollback is a plugin which lets you easily revert to any previous version, for any plugin or theme in the WordPress directory:

If you figure out a certain version breaks your site, keep note of that, it’s very valuable information for the plugin developer if you have to submit a support ticket.

What if none of this helped and your site is still broken?

Is the Problem Theme-Related?

If the problem didn’t resolve when you turned off plugins, it’s time to see if the issue is caused by your theme.

This is easily done simply by activating one of the default WordPress themes. The default WordPress themes are the ones that come bundled when you install WordPress. You can identify them by their name  – Twenty Sixteen, Twenty Seventeen etc. Always keep one of these available for activation for troubleshooting.

If the problem resolves when you activate the default theme, you know the issue is your theme.

If you cannot access your admin area, you can force WordPress to activate the default theme (if one exists on your site), by renaming the folder of your current theme. This is very similar to renaming the plugins folder.

In this example, Origin is the theme I use, so I’ll rename it to off.origin:

This forces WordPress to deactivate that and look for a default theme to use instead:

If you use a premium theme, when updating it I recommend always keeping your current version as a backup in a separate folder, just in case the new version gives you problems.

If the problem persists even after testing plugins and themes, we have to go on the hunt for more clues.

Looking for Clues: Changelogs

Well, I’m not going to lie, software changelogs are usually pretty boring. But they can certainly save your hide when you can’t figure out why something broke. For example, I had a case where after updating some plugins for a client, some pages of her site showed only a shortcode instead of the content the shortcode was supposed to generate. After racking my brain, trying multiple steps and having an internal meltdown, I read the changelog for the plugin and discovered the developer had decided to change the shortcode without backward compatibility :( So all instances of the shortcode had to be changed to the new shortcode. Had I read that first, I would have saved myself some stress and time.

Ideally, before updating a plugin or theme, click the “view details” link and take a glance at what’s changed:

In reality, I know you’re not going to read every changelog before updating every plugin ;) But keep it in your back pocket as a troubleshooting step.

Looking for Clues: Error Logs

Error logs are very valuable, especially if the problem you’re having is the white screen of death.

Where to find your error log

The error log can usually be found either in the  root folder of your WordPress installation – it’s simple a file named error_log – and/or in your hosting control panel. Depending on your host and the type of server you have, there may be a separate folder named logs and you’ll find the error log within that.

If you’re not able to locate the log on your server, get in touch with your webhost, or you can activate WordPress’ own logging system: wp_debug.

Enabling WP_DEBUG

To do this, you will need to edit the wp-config.php file.

Add the following lines:

define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

This will produce a log file, called debug.log,  in the wp-content folder:

How to read an error log

PHP generates different types of messages in the error logs. You may see a combination of Warnings, Notices and Fatal Errors. For troubleshooting purposes, you’re looking for Fatal Errors – these will break your site. Warnings and Notices generally won’t break your site.

If you’re facing the white screen of death, the error log is generally your best recourse – it’s usually caused by some fatal PHP error in the background that causes your site to stop loading properly.

Looking at an error message, whether on the white screen that was formerly your website, or in an error log is another place where people freak out because it looks like unintelligible gibberish. But you don’t have to understand the full contents of the error message in order to get something useful out of it.

The goal is to determine where the error is coming from, such as a specific theme or plugin.

If the message is very long, it might be easier to start at the end of the message, which should reference a specific line number, and work backwards until you recognize the name of your theme of a plugin.

I’m not a hardcore PHP developer, so I don’t fully understand what this error message is all about. But what I can see is that it references a specific plugin – the Eventbrite add-on for The Events Calendar. I’ve underlined the part that lets me know that. So now I know that I can deactivate this plugin and most likely get my set up and running again.

Not all error messages are generated by themes and plugins, of course. But those are definitely the easiest to deal with. Even if you can’t make sense of the error message, copy/paste it somewhere for safe-keeping, since it will be useful when submitting a support ticket or asking for help.

Another common one is the memory error:

Fatal error: Allowed memory size of 157286400 bytes exhausted (tried to allocate 5775295 bytes)

This is a very common cause of the “white screen of death”, but it can also cause other symptoms, like pages not fully loading, for example.

In most cases you can fix this error yourself by following this tutorial. Sometimes you have to contact your webhost about it if they are imposing some limitations.

What About Other Random Issues? Say, 404 Errors?

If you are experiencing strange 404 errors when you click on pages on your site, the first thing to try is simply flushing the permalinks. You do this by going to Settings > Permalinks and simply clicking Save. That’s it.

A common case where you need to do this is when you first activate the Yoast SEO plugin, specifically the XML sitemap feature. Sometimes, the first time you click on it, you get a 404 error. Instead of writing angry forum posts or leaving Yoast mean, 1-star plugin reviews, first try going to Settings > Permalinks and clicking save. 99% of the time, that’s all that is needed.

This 404 error can happen in any case where you add a plugin or theme which adds custom post types to your site, such as events, portfolio, products etc. If you get a 404 the first time you click on one of these new items, flush the permalinks.

500 / Internal Server Error

If that does not solve the weird 404 error, or if your issue is something like a 500 internal server error, it’s time to look at the .htaccess file.

The .htaccess file is used for all kinds of things – security rules, caching rules, redirects and more, which can be added by plugins. There can be conflicts for a multitude of reasons, and if there are, your site can become inaccessible. It’s one of the first files invoked when your site is loaded, so htaccess errors can certainly take it down.

To check if something in the .htaccess file is causing the problem, do the following:

1. Make a copy of the file,  so that you have a backup of any custom rules that might be in there
2. In the original file, remove everything except the default WordPress rules, which is the following block:

# BEGIN WordPress

RewriteEngine On
RewriteBase /
RewriteRule ^index\.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]

# END WordPress

*Note: this assumes you’re running a single WordPress site. The default rules on a multisite setup will be different, but should still have the surrounding comments, i.e. #BEGIN / END WordPress.

Now check your site. If the site is back up, it means there is indeed a conflict being caused by something in the content you removed.

If you’re feeling brave you can test to find out which section is the problem by putting the rules back, a section, or even a line at a time to see if you can isolate the conflicting part.

Other Causes

These are just a few of the problems you might face on your WordPress site. There are numerous other possible, miscellaneous causes, including:

• Server issues – check with your host
• File permission issues
• Caching issues
• Have you been hacked? (a plugin like Sucuri, SecuPress or Wordfence can help identify a hack)

How to Get Help

So you’ve isolated the issue and it’s time to ask for help or submit a support ticket. Please follow a few simple guidelines that will get you the best help, and will keep the internet a friendly place 😃

• Use Google
  Google is your best friend. It’s likely that whatever issue you are facing, someone else has already experienced, solved and  written a blog/forum post about it. Do a Google search for error messages and weird behaviour and you’ll likely find your answer.
• Facebook : There are groups for every skill level, and many of the popular themes and plugins have their own dedicated communities.
• Forums / Support Tickets
  • Include as much supporting info as possible:
  • Screenshots
  • Error messages
  • Version info
  • Webhost
  • Steps you’ve tried
  • How to reproduce the error
  • If the problem is visible, provide the URL
  • Be nice!

Preventative Best Practices

To limit the chances of something horrible going wrong on your live site, here are a few best practices to follow:

• Run all updates (WordPress, plugins, theme) on a staging or local version of your site first. Don’t know how to create a local, test site? Read this tutorial.
• Choose a webhost that provides regular backups and a staging site by default
• When updating, do one thing at a time and check your site each time
• Read this guide on how to  responsibly update your WordPress site
• Keep up with updates so it’s easier to do one at a time
• Choose plugins and themes that are actively developed, they are more likely to stay compatible with new versions of WordPress
• Invest in premium themes and plugins so that you have access to support and an active development process
• Set up scheduled, automated, regular backups – worst comes to worse, you can always restore from a backup. My current favorite plugin for this is UpdraftPlus.