Trying to deal with the 503 error in WordPress?
The 503 error, AKA 503 Service Unavailable error, 🐞 displays when your WordPress site’s server is unavailable for some reason.
It may seem like a scary error to see, but the source of the error can be found with some methodical troubleshooting. Read about what causes the 503 error in WordPress and how you can fix it. 🔧
What is the 503 error in WordPress?
The 503 Service Unavailable error shows when your web server is unavailable for some reason. Unfortunately, the error doesn’t tell you specifically what’s wrong, which means it can take time to fix the error.
Depending on the hosting setup and your web browser, you might see one of the following variants of this error:
- 503 Service Unavailable
- 503 Service Temporarily Unavailable
- HTTP Server Error 503
- HTTP Error 503
- Error 503 Service Unavailable
- The server is temporarily unable to service your request due to maintenance downtime or capacity problems. Please try again later.
When a 503 error is present, your whole website will be unavailable, including the WordPress admin. 🐛
What causes a 503 error in WordPress?
503 errors can be caused by server maintenance, a DDoS attack, bad code in a code snippet, plugin, or theme; or heavy traffic on the server, particularly if you are using shared hosting, where resources are limited.
If the 503 error is caused by maintenance, a DDoS attack or a spike in traffic, it may resolve itself after a short time. If it is caused by a bad piece of code, it may recur until you address the issue.
How to fix a 503 error in WordPress
Before you begin implementing the steps below, it’s worth checking out a couple of things.
Firstly, have you been running updates on your site? It’s possible that a 503 error will show when your site is in maintenance mode. Wait a few minutes for the update to conclude, then refresh your browser.
Secondly, check with your host that your server isn’t suffering an outage, or planned maintenance is occurring. Check your host’s service status page and your email inbox to see if you’ve been notified of a problem.
If you weren’t running an update and your host doesn’t indicate a problem with their servers, you can begin the following troubleshooting steps.
- Deactivate plugins
- Switch to a default theme
- Disable content delivery network
- Deactivate WordPress Heartbeat API
- Enable wp_debug mode
- Upgrade your hosting plan
Deactivate plugins
A badly coded plugin may be the source of the 503 error in WordPress. To check this out you will disable all plugins and attempt to identify a rogue plugin.
Since you can’t access the wp-admin, you will need to use an FTP client to access the plugins directory (or a tool like cPanel File Manager).
Connect to your home directory using FTP. The home directory is typically called one of the following:
- public_html
- www
- html
- public
- your site’s name
From the home directory, navigate to the wp-content
directory and find the plugins
directory.
Right-click on this directory and use the Rename function to rename it to plugins_old
.
Now that you have changed the directory name, all your plugins will be deactivated. Check your website to see if the 503 Service Unavailable error persists.
If the error has gone away, it’s likely that one of your plugins is the culprit.
To identify the problem plugin, follow these steps:
- Change the plugins_old directory back to plugins.
- Navigate into the plugins folder.
- Start with the first plugin in the list and rename the plugin folder e.g., change antispam-bee to antispam-bee-test.
- Check your website for the 503 error. If it appears, you know which plugin is causing the error.
Now, you’ll need to keep that plugin deactivated 🔌 and look for an alternative.
Switch to a default theme
Another possible source of 503 errors is your theme. To test this, you can switch your site to one of the default themes that is loaded with WordPress, like Twenty Twenty Three.
Unfortunately, you can’t use the same trick as for plugins and rename the themes folder. If you do, WordPress will throw an error, saying that The theme directory "[theme-name]" does not exist
.
Instead, you need to use phpMyAdmin to access the WordPress database, and change the active theme there.
⚠️ Note – we’re assuming that you still have the default Twenty Twenty-Three theme installed on your site. If you deleted the default theme, you might need to first install it using FTP – you can manually upload the theme folder to your site’s wp-content/themes
folder.
Login to phpMyAdmin via your hosting control panel, and look for the wp_options
table. Depending on your host, it might have a different prefix from wp_
– for example wpcz_options
.
Click the search link and perform a search on the table for the word template
in the option_name field.
You should have one result. Double-click on the option_value (genesis in this example) and rename the theme to twentytwentythree.
Here’s what it should look like when you’re finished:
Repeat the same step for the stylesheet
option_name.
Now you have updated the active theme, visit the front end of your site to see if the 503 Service Unavailable error remains.
If the error appears to have cleared, it’s likely that your theme was the problem.
If changing themes permanently is an option for you, feel free to do that. Otherwise, contact your theme provider and report the 503 error to them.
It’s possible that there may have been a theme update recently which caused the error, so you may be able to revert to an earlier version of the theme. Or there might be an updated version you can download which fixes the bug.
Disable content delivery network (if you’re using one)
If you’re not using a CDN, skip this step. If you are, read on.
Sometimes a CDN can be the source of a 503 error in WordPress. To test for this, your CDN should have the means to pause the service. On Cloudflare, you can find this option in the Advanced Actions section of your Quick Actions menu, which is on the right-hand side of the Overview screen (scroll down to see it).
If pausing your CDN fixed the issue, you probably don’t want to disable your CDN long-term, so reach out to your provider for assistance.
Deactivate WordPress Heartbeat API
The WordPress heartbeat API controls several essential functions on WordPress. For example, the following actions are heartbeat controlled:
- autosaving posts
- locking the editor to prevent two users editing the same post simultaneously
- dashboard notifications
The heartbeat API sends pulses from the client to the server, communicating using AJAX. The file used is /wp-admin/admin-ajax.php. This results in large numbers of requests to the server, which can be a problem if you are using shared hosting and have limited resources.
To see whether the WordPress heartbeat API is causing the 503 error in WordPress, you can disable it temporarily by adding some code to the functions.php file of your active theme.
Use your FTP editor to access your theme directory. Right-click on your functions.php file to edit it (you may wish to take a backup first).
Add the following code after the initial
add_action( 'init', 'stop_heartbeat', 1 );
function stop_heartbeat() {
wp_deregister_script('heartbeat')
}
Code language: JavaScript (javascript)
Save your changes to the file, then try accessing your site again to see if the 503 error persists. If it’s gone, you know that the heartbeat API was responsible.
Unfortunately, disabling the heartbeat API will stop a lot of useful functionality, so it’s better to limit the heartbeat instead. You can use the Heartbeat Control plugin to do this. Just remember to remove the code to disable the heartbeat from your functions.php first.
Enable wp_debug mode
The debug mode is built into WordPress as a way to troubleshoot errors. It’s not enabled by default, so you need some code to activate it.
Use your FTP client to access your wp-config.php file. Edit it and add the following lines of code to it:
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
Code language: JavaScript (javascript)
Save and reupload the file.
Now look in your wp-content directory for a file called debug.log. This logs any errors found on your site. The log file tells you which file was responsible for each error and the line(s) of code responsible. The debug.log file won’t tell you what’s causing the 503 error in WordPress but it will give you clues as to where to look next.
You can also look up your web server’s debug logs, normally found here:
- Apache: /var/log/apache2/error.log
- Nginx: /var/log/nginx/error.log
Contact your hosting provider for more help interpreting log files if you need it.
Upgrade your hosting plan
If you haven’t been able to pinpoint the source of your 503 error, but suspect your hosting is responsible, you may want to look into upgrading your hosting plan. This applies especially in a couple of cases:
- You are using shared hosting and you are overrunning your server resources.
- Your website is getting more popular and your traffic has increased.
If you are using shared hosting, it might be time to consider managed hosting. Talk to your hosting provider about upgrading your plan. In some cases, you might want to switch web host altogether.
👉 Consult our best web hosting guide to see what we recommend for different types of hosting.
Fix the 503 error in WordPress for good 🎯
If you see the 503 error in WordPress, don’t panic. The troubleshooting steps are:
- Deactivate plugins
- Switch to a default theme
- Disable CDN if using
- Deactivate WordPress Heartbeat API
- Enable wp_debug mode
- Upgrade your hosting plan
📌 Hopefully, these steps will enable you to discover the source of the 503 error and end your woes.