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.
📚 Table of contents:
- Good practice when running a WordPress site
- Before troubleshooting WordPress
- Common WordPress errors
- Learn more about troubleshooting WordPress
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.
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 WordPress.com.
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.
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:
- Restore a recent backup that includes your database
- Check for corrupted WordPress theme and plugin files
- Reinstall WordPress core files
- 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:
And you might get an email like this:
Solutions you can try to fix the white screen of death include:
- If the error occurred after a WordPress update, check the server to see if a
.maintenancefile exists and delete it.
- 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-contentfolder 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_disabledfolder back to plugins, and reactivate them one by one to see which one is at fault.
- Try a default WordPress theme. You can do this in Appearance → Themes 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.
- Clear your browser cache and WordPress cache.
- 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 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.
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 Settings → Permalinks 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:
- Turn on debugging
- Deactivate all plugins and switch themes
- Check your
- Increase your memory
- Ask your host
- 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: