Skip to content

A Beginner’s Guide to Troubleshooting WordPress (Step-by-Step)

Need help with troubleshooting WordPress?

No matter how reliable the WordPress software is, you’ll probably run into some situations where you need to fix a problem. And when that happens, you’ll want to know how to go about troubleshooting WordPress.

This post is here to help. Below, we’ll not just teach you how to fix some common WordPress problems, but we’ll also go over some tips for frameworks and how to approach troubleshooting in general. This will give you the tools you need to fix the problem, even if it’s not one of the common WordPress errors that we cover in this post.

Troubleshooting WordPress.

📚 Table of contents:

Before we start troubleshooting, it’s useful to look at things that make your life easier running a WordPress website, which help when things go wrong.

How to maintain your WordPress site (to avoid troubleshooting) 🖱️

As they say, an ounce of prevention is worth a pound of cure.

With that in mind, the first step in your WordPress troubleshooting journey is to make sure you’re doing the little things to keep your site well-maintained.

This will not just prevent issues from happening in the first place, but it will also make sure that you can more easily find the actual problem if something does go wrong.

Keep WordPress up to date

New major versions of WordPress (e.g., 6.3) are released three or four times a year, with minor updates (e.g., 6.3.1) added in between.

It’s important to keep WordPress up to date for several reasons:

  • The latest version of WordPress has the latest security updates and bug fixes.
  • Updating WordPress introduces new features. An example comes from WordPress 6.3: WordPress auto-restores the previous version of a plugin or theme if an update fails.
  • Major updates of WordPress feature performance updates, so your site runs faster and more smoothly.
  • WordPress updates improve compatibility with plugins and themes.

Update plugins and themes

Just as important as updating WordPress is keeping your plugins and themes updated. The reasons are similar to those for Core updates. New versions bring increased features, security improvements and bug fixes.

Sometimes updating is urgent because a security vulnerability is found in a plugin or theme, which could be exploited by a hacker. For example, the popular Yoast SEO plugin version 20.2 and lower have a DOM-based Cross-Site Scripting vulnerability, which was corrected in version 20.2.1. You can check plugin vulnerabilities in the WordPress vulnerability database by Wordfence.

Take regular backups

Regardless of what your host might do, it’s a good idea to take regular backups of your site. The backup frequency will depend on your type of site. If you’re running a blog which you update a few times a week, daily backups may be needed; if you have a busy ecommerce site you might want hourly backups.

Just as important as taking backups is actually testing that you can restore your site from them. Don’t be tempted to skip this step!

Set up a staging site

If you are making major changes to your site or have a large number of Core, plugin and/or theme updates to do, setting up a staging site is a smart idea. A staging site is a copy of your live site built for testing purposes. The advantage of using one is that if you make a change that doesn’t go according to plan, your live site is still intact and reachable.

Staging sites are a feature usually included with managed WordPress hosting; check out our guide to 11 managed hosting providers to see hosts that offer it.

Now we’ve gone through the WordPress good practice list, let’s look at how to begin troubleshooting WordPress.

What to do before troubleshooting WordPress 💡

Before you get started on troubleshooting WordPress, following these steps will help you keep a clear head.

As with the maintenance tips above, they’ll also help you rule out basic errors that could be making a very small problem seem like a bigger one, like caching issues.

Read documentation

The WordPress documentation takes you through the basics of how WordPress operates. The FAQ Troubleshooting and Common WordPress Errors articles are your friend here.

Themes and plugins should have their own documentation which may list out common errors and how to solve them. An example is the Jetpack plugin, which documents errors that you might see when connecting your site to

Clear browser cache and cookies

Clearing browser cache and/or cookies “resets” the browser and can cure errors such as content not being updated.

Note that clearing cookies will sign you out of most websites, and you’ll have to log in again.

Find out how to clear browser cache and clear cookies.

Clear WordPress cache

If you’re using a WordPress caching plugin, you’ll want to clear the cache in the plugin if you’ve made a recent change to your site.

Find out how for popular caching plugins:

If you haven’t implemented caching and want a site speed and performance boost, check out our guide to the top five caching plugins.

In case your host offers a server-level caching feature, you might also need to clear the cache via your hosting dashboard.

Your host might also implement caching at the CDN level. Then, you would need to clear the CDN cache as well.

Inspect error logs

Error logs can be a mine of information about activity on your site. You can set up error reporting for WordPress by turning on the option in wp-config.php. Simply open up the wp-config.php file, navigate to the line define( 'WP_DEBUG', false ); and change false to true. Then save the file on your web server.

Alternatively, you can use a plugin like WP Debugging.

If you’re not sure where your error logs are stored, ask your host to help you out.

Google the error

Finally, Googling the error you encounter can prove fruitful. Make sure you search for a specific error, rather than “WordPress is broken.” You may find links to blog posts, videos or WordPress forum posts which will help you when troubleshooting WordPress errors.

Search results for the error establishing a database connection in WordPress.

Common WordPress errors and how to troubleshoot them ⚠️

Now that you know some general WordPress troubleshooting tactics, let’s take a quick look at fixing some of the most common WordPress errors you might experience.

Error establishing a database connection

This error means that WordPress cannot communicate with the database. It can be caused by an error in the credentials in the wp-config.php file. You should double-check the information you have from your host to see if you have mistyped something.

If the information is correct, you may have an issue with your host, if the database is down. Check with them to see if that’s the case.

Otherwise, you can try one of these four steps:

  1. Restore a recent backup that includes your database
  2. Check for corrupted WordPress theme and plugin files
  3. Reinstall WordPress core files
  4. Use WordPress’ database repair functionality

For a full guide, check out Themeisle’s post on fixing the Error Establishing a Database Connection problem.

Posts and pages not updating

If you’ve updated your posts or pages but you’re not seeing the changes on the frontend of your website, you probably have caching issues. Follow the steps above to clear your browser or WordPress cache.

WordPress is stuck in maintenance mode

WordPress implements a maintenance mode when you update WordPress, plugins or themes. While the update is taking place, your site should show a message that reads: “Briefly unavailable for scheduled maintenance. Check back in a minute.” But sometimes it can get stuck in that mode when updates are completed. This means that your site is inaccessible.

The answer to this question is simple. Delete the .maintenance file that’s on the server (which generates the maintenance message) using FTP.

For full instructions on how to do that, check out Themeisle’s guide on fixing WordPress stuck in maintenance mode.

WordPress white screen of death

The white screen of death is one of the most annoying errors to fix because it doesn’t give you any information about what is wrong with your site. All you will see is a blank white screen.

The white screen of death can be caused by:

  • A script on your website exhausting the memory limit
  • PHP errors
  • An issue with one of your plugins or themes

If a plugin or theme is causing the problem, you might see an error message like this:

There has been a critical error on this website.

And you might get an email like this:

Your site is experiencing a technical issue email.

Solutions you can try to fix the white screen of death include:

  1. If the error occurred after a WordPress update, check the server to see if a .maintenance file exists and delete it.
  2. Disable your WordPress plugins. You can do this on the Plugins section of your WordPress admin. If the admin area is inaccessible, you can do this via FTP by accessing the wp-content folder on your server and renaming the folder to plugins_disabled. This will deactivate all your WordPress plugins. If your site is accessible now, you know that a plugin is at fault. Then you can rename the plugins_disabled folder back to plugins, and reactivate them one by one to see which one is at fault.
  3. Try a default WordPress theme. You can do this in AppearanceThemes if the wp-admin area is accessible, or alternatively change theme via the database using phpMyAdmin. If the error goes away, you know that your theme is at fault.
  4. Clear your browser cache and WordPress cache.
  5. If you’re seeing a memory error, increase your memory limit. You can do this in wp-config.php by adding the following line: define(‘WP_MEMORY_LIMIT’, ’64M’); .

404 errors

404 page not found errors are caused by a user requesting a page or resource that isn’t found. Sometimes this will happen because they’ve mistyped a URL, but at other times the page might have been deleted or moved.

CodeinWP 404 error page.

To detect 404 errors on your site you can use the Broken Link Checker plugin.

And to correct 404 errors caused by a web page being deleted or moved, you can use the Redirection plugin to set up a 301 redirect. You can even implement server-side redirects on Apache and Nginx.

If you’re seeing 404 errors on a large number of pages, that suggests an issue with your permalinks. Go to SettingsPermalinks in the menu and click on the Save Changes button.

Internal server errors

Internal server errors (error 500) are caused by something going wrong on your host’s end. These errors will block access to your website. In WordPress, they can be caused by a faulty theme or plugin.

When you encounter this error, you can try reloading the page or clearing your cache to see if they help. If the error persists, you can try the following steps:

  1. Turn on debugging
  2. Deactivate all plugins and switch themes
  3. Check your .htaccess file
  4. Increase your memory
  5. Ask your host
  6. Reinstall WordPress

For full instructions on resolving internal server errors, you can follow Themeisle’s guide on how to fix the 500 Internal Server Error for WordPress sites.

Learn more about troubleshooting WordPress 👨‍🎓

That wraps up our general guide to WordPress troubleshooting, along with some quick fixes for common problems.

If you want to learn how to fix even more problems, you can also read our full list of 20+ common WordPress errors and fixes.

⚙️ Some other useful forms of support in troubleshooting WordPress are:

What’s your go-to resource for troubleshooting WordPress? Let us know in the comments.

Don’t forget to join our crash course on speeding up your WordPress site. Learn more below:

Yay! 🎉 You made it to the end of the article!
Claire Brotherton

Inline Feedbacks
View all comments

Or start the conversation in our Facebook group for WordPress professionals. Find answers, share tips, and get help from other WordPress experts. Join now (it’s free)!

Would love your thoughts, please comment.x

Most Searched Articles

Best JavaScript Libraries and Frameworks: Try These 14 in 2024

In this post, we look at the best JavaScript libraries and frameworks to try out this year. Why? Well, with JavaScript being available in every web browser, this makes it the most accessible programming language of ...

20 Best Free WordPress Themes for 2024 (Responsive, Mobile-Ready, Beautiful)

If you're looking for only the best free WordPress themes in the market for this year, then you're in the right place. We have more than enough such themes for you right ...

12 Best WordPress Hosting Providers of 2024 Compared and Tested

Looking for the best WordPress hosting that you can actually afford? We did the testing for you. Here are 10+ best hosts on the market ...

Handpicked Articles

How to Make a WordPress Website: Ultimate Guide for All Users – Beginners, Intermediate, Advanced

Many people wonder how to make a WordPress website. They’ve heard about WordPress, its incredible popularity, excellent features and designs, and now they want to join the pack and build a WordPress website of their own. So, where does one get ...

How to Start an Ecommerce Business: Ultimate Guide for 2024

Is this going to be the year you learn how to start an eCommerce business from scratch? You’re certainly in the right place! This guide will give you a roadmap to getting from 0 to a fully functional eCommerce business. ...