WordPress.org
Get WordPress

Troubleshooting Basics

In this lesson you’ll learn about the basic troubleshooting steps that can be taken when something goes wrong on your WordPress site.  The lesson will focus on troubleshooting an existing install of WordPress and will not deal with issues during installation.  This basic troubleshooting will fix a lot of common issues avoiding the need to spend hours researching and waiting for answers on the WordPress Support Forums.

Objectives

After completing this lesson, students will be able to list basic troubleshooting steps to resolve many common issues.

Prerequisite Skills

  • Basic knowledge of WordPress Dashboard.
  • Comfort with activating and deactivating plugins.
  • Comfort with switching and activating themes.
  • Comfort with manipulating and editing WordPress files via FTP.

Assets

You will need:

  • An active WordPress install.
  • An FTP client.

Screening Questions

  • Are you familiar with switching and activating themes via the WordPress Dashboard?
  • Are you familiar with activating and deactivating plugins via the WordPress Dashboard?
  • Are you familiar with manipulating WordPress files via FTP?

Teacher Notes

  • The ideal student will be able to answer yes to most of the screening questions.
  • A lack of familiarity with FTP and file manipulation does not eliminate the ability to take the course.

Hands-on Walkthrough

Take a deep breath! Walk away.

It is easy to become frustrated when we can’t solve a problem immediately. As a result of our frustration, our vision becomes more narrowly focused. We then repeat the same actions over and over or make assumptions about what the problem is and don’t look beyond that. We close our mind to other possible causes to the problem or are so overwhelmed by the problem that we don’t know where to start to solve it.

The first step to solving any problem is to relax. While it may seem like the world is ending, it is not. The site may be temporarily broken or not working as expected, but you are more likely to get it working the way you want if you take a deep breath and a break and approach the problem fresh. When you are feeling more relaxed, you can work through the following exercises to define the problem more clearly and find a solution.

A well-defined problem is half the solution!

Most computer-related and software-related problems are not random. With the exception of a hardware failure, all software-related problems follow a logical and linear progression of cause and effect.

Half of the solution to your problem lies in defining the problem. Once you have defined the problem, the solution is close at hand. In defining the problem, we need to be as specific as possible in our description. Instead of saying, “The theme does not work,” we may say, “When I updated the theme, my header image disappeared.”

To begin to solve the problem, first identify when the problem occurs, then see the specific areas below for how to troubleshoot issues with that specific event. Most commonly, problems occur:

  • After installing and activating a new plugin or theme
  • After updating WordPress core, a plugin, or theme
  • After modifying a template file, functions file, or stylesheet

Think about what happened right before the problem occurred. This will help you narrow down the source of the problem.

Identifying variables

In addition to identifying when the problem occurs, we need to identify other variables in our WordPress installation that may be effecting how our site is functioning. Take time to note the following:

A – Hosting

  • Who is your web host?
  • What version of PHP and MySQL are they running on your hosting account?
  • Do these match the recommended software versions on the WordPress Requirements page?

B – WordPress

  • What version of WordPress is running?

To find the version of WordPress you are running:

  1. Login to your WordPress site.
  2. Click the Dashboard icon at the top of the Dashboard sidebar.
  3. Take note of the WordPress version under the At a Glance panel:
At A Glance in WP Dashboard

What version of WordPress are you running? Is it the most current version? If it’s not the most current version, you will see an Update button in the At a Glance panel:

At A Glance in WP Dashboard with an update

C – Plugins

  • What plugins are installed?
  • Are all the plugins current?
  • Are there any plugins that haven’t had updates in a while? Find the plugin you are using on WordPress.org (or from the paid plugin developer) and look at the last update date. Do you have the current version? Does it appear the plugin is no longer maintained?

D – Themes

  • What theme are you using? (See Troubleshooting Themes)
  • Is the theme the current version? You can check this via the Theme Directory or by checking your Dashboard > Updates page for updates.

E – Cache

  • Browser
  • Web host
  • Plugin

F – Local computer environment

  • Browser and browser version
  • Computer operating system and version
  • Network, router, ISP

Replicating the problem and eliminating variables

1 – Replicate the Problem

In order to find the best solution, it’s important to narrow down what specifically is causing the problem. One of the best ways to do that is to attempt to repeat the problem, so you can identify the specific action causing it.

Can you list out and identify the specific steps you take to encounter this problem? For example, what are you attempting to do when it happens? What is the expected outcome, and what happens instead? It is better to note too much detail than too little – even if it seems obvious, try to include the most basic steps.

2 – Eliminate Variables

Sometimes a bug or unexpected behavior may be caused by additions to your site that are not interacting as expected. In order to pinpoint the cause, eliminating variables can help you to identify if there is a third-party service, a plugin, or theme that might be triggering the error.

First, you can try deactivating any active plugins one-by-one. Going one-by-one will help you to identify which plugin specifically may be causing the conflict. You can do this via your Plugins > Installed Plugins page, clicking on Deactivate under each plugin, and then re-testing the steps to reproduce the issue.

Active plugins page

If deactivating your plugins doesn’t resolve the problem, you can also test for a theme conflict, as well, by switching to one of the default themes, like Twenty Twenty or Twenty Nineteen.

3 – Test on a fresh install

Another way to eliminate variables is to simply try to reproduce the problem on a fresh installation of WordPress. Depending on your hosting set up and your level of familiarity with installing WordPress, you can create a new test site or work on a local install of WordPress. (See the Local Install lesson plan.)

Once you have a fresh install created, follow the steps you outlined above to try to reproduce the problem. This can also help to confirm if the issue is with WordPress itself, or with a customization made to your install at some point along the way.

Common Errors and Prevention

While this is, by no means, an exhaustive list, we’ve shared a few common scenarios below that might cause site owners to wonder what went wrong. We’ll also cover some helpful best practices.

White Screen of Death

The White Screen of Death (WSOD) is a pretty generic error that can be caused by a number of factors. When it happens, you’ll know – when visiting your site, you won’t see your content, but just a white screen!

It can be scary when this happens. As mentioned above, it’s important to relax and take a breath. Nope, it’s very unlikely that you’ve lost your site’s content and will be able to fix things with just a bit of digging. (Better yet, as long as you’re following the “Best Practices” below, you’ll also have back-ups to help you, as well.)

The most common causes of the White Screen of Death are compatibility issues with either a plugin you’ve installed, or the theme you’re using. In either case, you’ll want to follow the instructions we listed above by deactivating your plugins or switching to a default theme.

Sometimes, this error can cause your site’s Dashboard to be unavailable. In that case, you can switch themes or deactivate plugins by connecting to your site through FTP.

  • Plugins: To deactivate all of your plugins via FTP, locate your wp-content/plugins folder and rename it to plugins-old.
  • Theme: To change your site’s theme via FTP, locate the theme you’re using in your wp-content/themes folder and rename the folder for the active theme.

Once you’ve done this, try to access your site once again via the Dashboard to continue to troubleshoot.

Stuck in “Maintenance Mode“

After updating the version of WordPress that you’re using, you may run into seeing the following message on your site.

Maintenance mode message after WordPress update

When WordPress updates, it automatically installs a .maintenance file. When your site gets stuck with this error message, it typically just means that the .maintenance file wasn’t deleted automatically my WordPress after finishing the update. To fix it:

  • Log into your website using your FTP program of choice.
  • Search for the .maintenance file, which will be found in your site’s root folder.
  • Delete the .maintenance file.

Missing Dashboard element

When following a tutorial, there may be times when your Dashboard doesn’t quite look like what you see in the video. When this happens, this is frequently caused by your Screen Option settings.

Screen Options appear as a tab at the top of every page on your Dashboard. When clicked on, this tab opens a list of all of the widgets/elements on that Dashboard page and a checkbox to toggle whether or not those elements are visible.

Screen Options settings

To fix a missing element, try toggling the related item in your Screen Options tab to turn on any missing elements from your page.

Best practices

Best practices are recommended actions to help pro-actively prevent potential issues with your site. It is recommended that you:

  • Keep your site up-to-date. This includes using the latest version of the WordPress software, as well as any plugins or themes that you have installed.
  • Use the Site Health Status tool in your Dashboard to regularly check for any improvements or updates that can be made to your site’s overall health.
  • As part of your Site Health check, regularly remove inactive plugins or themes that are no longer being used on your site.
  • Regularly back-up your site, including databases, media files, plugins, and themes. You can check with your hosting provider to see if they offer a back-up solution or search the WordPress.org Plugin Directory for plugins that offer back-up solutions.

Where to find help

Sometimes, it’s not possible to fix an error on your own. And that’s okay! Knowledge is power. With all of the steps and tools you know to use already, that additional information will help you when you need to reach out to others for assistance.

But where to get help? The two best places two start are: with your hosting provider and in the WordPress.org support forums. In either case, it’s often a good idea to search the support forums on your own to see if anyone else has ever come across the issue before.

One of the great things about the WordPress.org support forums is that forum topics are saved and searchable. This means that if someone had a similar issue to yours in the past, you might be able to find the help you need just from the instructions and tips they received. Likewise, when you post your own question in the forums, others may benefit from what you’ve learned, as well.

Exercises

Deactivating themes and plugins.

On a test site, ask students to:

  • Individually deactivate plugins to see the effect the change has on their site.
  • Switch to a default theme, like Twenty Twenty, and then back to their current theme to improve their familiarity with how this might look when troubleshooting.

Explore the WordPress.org support forums and documentation.

Ask students to explore some of the more recent threads in the WordPress.org support forums. Ask them to:

  • Pick a topic and note what resources they might use to help solve the problem.
  • Reflect on the responses given.
    • Do any of the steps suggested by forums volunteers match what we’ve shared here?
    • Did they find any new resources or interesting features in reviewing this thread?

Quiz

What is not a variable in your WordPress installation?

  1. Your hosting provider
  2. The version of WordPress you’re using
  3. Your domain name
  4. Plugins + themes

Correct Answer: 3. Your domain name

What is causes a site to get stuck in “maintenance mode”?

  1. A setting in your Dashboard
  2. A .maintenance file that wasn’t automatically deleted during update
  3. Activating a maintenance mode plugin

Correct Answer: 2. A .maintenance file that wasn’t automatically deleted during update

Where can you get help for your site?

  1. The WordPress.org support forums
  2. A tech-savvy friend
  3. Your hosting provider
  4. All of the above

Answer: 4. All of the above

Additional Resouces