Troubleshooting WordPress Issues

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)