Troubleshooting · Troubleshooting
How to Fix the 503 Service Unavailable Error in WordPress
Short answer
To fix the 503 Service Unavailable error in WordPress, first delete the hidden .maintenance file in your site root if the maintenance message shows, then re-run the interrupted update. If there is no maintenance message, turn on debug logging, disable plugins one at a time, and check server limits with your host. A 503 is temporary, so the fix is to find whether maintenance, overload, or a faulty plugin is behind it.
Key takeaways
- A 503 means the server is running but not ready to serve the page, usually because of maintenance or overload.
- WordPress shows 'Briefly unavailable for scheduled maintenance' during updates and sends a Retry-After header of 600 seconds.
- A stuck .maintenance file in the site root is the first thing to check after a failed update.
- If the error page names cloudflare or cloudflare-nginx, Cloudflare generated the 503; otherwise your origin server sent it.
- A 503 that lasts for multiple days can lead Google to drop the affected URLs from its index.
- Turn debug logging off again after you find the cause, and never show debug errors to visitors on a live site.
What does the 503 Service Unavailable error mean in WordPress?
A 503 Service Unavailable error means your server is running but is not ready to handle the request right now, so WordPress cannot load the page.
MDN, the web documentation maintained by Mozilla, defines the 503 status as a sign that the server is not ready to handle the request, with a server down for maintenance or overloaded as the common causes.
The key word is temporary. A 503 tells browsers and search engines that the page still exists and that they should try again later, not that the page is gone for good.
In WordPress, the most common 503 message reads "Briefly unavailable for scheduled maintenance. Check back in a minute." WordPress shows that message during core, plugin, or theme updates.
A 503 response can carry a Retry-After header that states when to try again. MDN says the header should contain the estimated time for the recovery of the service, if possible.
How is a 503 different from a 502, 504, 500, or 429 error?
A 503 means the server itself is not ready to serve the request, while 502 and 504 point to a failed exchange between two servers, and 429 points to rate limiting for one client.
| Code | Meaning | What it tells you |
|---|---|---|
| 500 | Internal Server Error | Something broke inside the server or app, not a capacity pause |
| 502 | Bad Gateway | A gateway got an invalid response from an upstream server |
| 503 | Service Unavailable | The server is up but not ready, often maintenance or overload |
| 504 | Gateway Timeout | A gateway waited too long for an upstream server to respond |
| 429 | Too Many Requests | One client is being rate limited |
MDN notes that if requests from specific clients are restricted by rate limiting, the right response is 429 Too Many Requests, not 503.
The practical difference is the fix. A 503 sends you to server capacity, maintenance mode, or limits, while a 502 or 504 sends you to the link between the gateway and the upstream server.
What causes a 503 error on a WordPress site?
Most WordPress 503 errors come from 5 causes, and the message on the page plus the timing usually points to 1 of them.
| Cause | Sign | First check |
|---|---|---|
| Stuck maintenance mode | “Briefly unavailable” message | .maintenance file in the site root |
| Server overload | Error starts during a traffic spike | Host resource graphs |
| PHP worker exhaustion | Site stalls under concurrent visits | PHP worker count |
| Faulty plugin or theme | Error starts after an update | Debug log |
| Overloaded origin behind a CDN | Error only shows through Cloudflare | Origin response |
MDN adds that some server-side applications reject requests with a 503 when resource thresholds like memory, CPU, or connection pool limits are met.
Overload is a safety valve. Dropping requests creates backpressure that stops the server from running out of compute resources, according to MDN.
How do you fix a stuck maintenance-mode 503?
Delete the hidden .maintenance file in your WordPress root folder, then re-run the update that was interrupted.
- Open your host file manager or FTP client and go to the WordPress root folder, the folder that holds wp-config.php.
- Turn on the option to show hidden files, since files that start with a dot are hidden by default.
- Look for a file named .maintenance and delete it.
- Load your site again and log in to wp-admin.
- Go to “Dashboard → Updates” and re-run the update that stopped halfway, so no half-updated plugin or theme is left behind.
WordPress creates .maintenance before an update and deletes it when the update ends. If the update stops halfway, the file stays and every visitor sees the 503 message.
WordPress also sends a Retry-After: 600 header with the maintenance page, which means 600 seconds, or 10 minutes. The core check treats maintenance mode as over once the timestamp inside the file is 10 minutes old, so a message that lasts far longer than 10 minutes has another cause too.
How do you find the cause when there is no maintenance message?
Turn on WordPress debug logging, reload the failing page, and read wp-content/debug.log for the last error before the 503.
Back up your site before you edit any files, and follow a guide on how to back up WordPress if you have no recent backup.
- Open wp-config.php in the WordPress root folder.
- Find
define( 'WP_DEBUG', false );and changefalsetotrue. - Add
define( 'WP_DEBUG_LOG', true );anddefine( 'WP_DEBUG_DISPLAY', false );above the line that reads “That's all, stop editing!” - Save the file, reload the page that returns 503, then open wp-content/debug.log.
WordPress's own debugging guide lists WP_DEBUG as the master switch, WP_DEBUG_LOG as the log writer, and WP_DEBUG_DISPLAY as the display control.
Keep display off on a live site. Developer.WordPress.org notes that WP_DEBUG_DISPLAY defaults to true, so turning on WP_DEBUG alone prints errors into the page for every visitor.
Turn debug mode off when you finish. Change WP_DEBUG back to false and remove the two extra lines, since a live site should not log errors to a public folder forever.
How do you disable plugins and themes to test for a 503?
Rename the plugins folder by FTP, then rename each plugin folder back one at a time until the 503 returns, which names the faulty plugin.
- Connect by FTP or open the host file manager and go to wp-content.
- Rename the plugins folder to plugins-off and reload the site.
- If the site loads, rename the folder back to plugins, then rename each plugin folder inside it one at a time, reloading after each one.
- When the 503 returns, the last plugin you restored is the cause, so leave it disabled and look for an update or a replacement.
If plugins are not the cause, switch to a default theme such as Twenty Twenty-Five by renaming the active theme folder in wp-content/themes, which forces WordPress to fall back to a default theme.
A faulty plugin or theme often shows up in the debug log first, so read wp-content/debug.log before you rename folders if you already turned on logging.
How do you check server limits and PHP workers?
Open “Tools → Site Health → Info → Server” in wp-admin and compare the PHP version and PHP memory limit with what your host plan allows, then ask your host about worker and process limits.
A PHP worker is a process that runs one WordPress request at a time, so when all workers are busy, new requests wait and can end in a 503. Learn more in the guide on what PHP workers are.
The number of workers your site needs rises with traffic and with slow requests, so check how many PHP workers you need for WordPress before you raise any other limit.
MDN notes that 503 responses appear when memory, CPU, or connection pool limits are met, which is why a traffic spike can turn a healthy site into a 503 page in minutes.
If the limits are the cause, the fix is a plan change, caching, or fewer heavy requests, not a plugin edit. Ask your host for the exact limit that was hit and the time it was hit.
What should you do when Cloudflare shows the 503?
Read the error page first: if it contains the words cloudflare or cloudflare-nginx, Cloudflare generated it, and if it does not, your origin server sent it.
Cloudflare's own 503 guide states that HTTP error 503 occurs when your origin web server is overloaded, and it tells you to separate origin errors from Cloudflare errors by checking the page body.
For an origin error, Cloudflare advises you to contact your hosting provider to check whether it rate limits requests to your origin web server.
For a Cloudflare-generated error, gather your domain name, the time and timezone of the error, and the output of yourdomain.com/cdn-cgi/trace, then send those 3 items to Cloudflare support.
Cache rules can also shape what visitors see during an outage, so review your Cloudflare cache rules for WordPress before you assume the origin is down.
Cloudflare also notes that a 503 visible only in logs or analytics can come from unsuccessful prefetches, which visitors never see, so check whether real visitors hit the error before you change anything.
How do you know the 503 is fixed?
Load the home page and 2 inner pages in a private browser window, then check that each returns a 200 status and loads fully.
- Home page loads without the maintenance message.
- wp-admin loads and you can save a test post draft.
- The debug log shows no new fatal error after you reload the failing page.
- A second visit 10 minutes later still loads, so the fix was not a short pause in traffic.
Do not trust a single reload. A 503 that clears for a minute and returns under load points to limits, not to a file you deleted.
A slow but loading site still needs work, so measure server response time after the fix and compare it with the time before the error.
When should you contact your host?
Contact your host when the 503 returns under normal traffic, when you cannot reach the server by FTP, or when the error log names a server limit you cannot change.
- The 503 appears on every page, including wp-admin, and no maintenance file exists.
- Your host dashboard shows CPU, memory, or entry process limits being hit.
- The error started after a host-side change, such as a PHP version change or a server move.
- Cloudflare's guide points to the origin, and you have no access to server logs.
Give the host the exact time of the error, the URLs that failed, and the last lines of the debug log. Those 3 items let support check the right minute in the server logs instead of guessing.
Google's crawler guidance adds a deadline: a 503 is fine for a day or 2, but if the same URLs return 503 for multiple days, Google may drop them from its index, so do not let a host ticket sit for a week.
What mistakes should you avoid?
Avoid these 5 mistakes, since each one turns a short 503 into a longer outage or a new error.
- Deleting the .maintenance file and never re-running the interrupted update, which leaves a half-updated plugin behind.
- Leaving WP_DEBUG on with display enabled, which prints file paths and errors to every visitor.
- Raising memory limits to hide a faulty plugin instead of finding the plugin that causes the error.
- Serving a 503 on robots.txt, which blocks all crawling, or serving an error page with a 200 status, which tells search engines the page is fine.
- Caching the 503 page, since MDN warns that 503 responses should not usually be cached, or visitors keep seeing the error after the fix.
Fix the cause in order, check the fix twice, and write down what changed, so the next 503 takes minutes to trace instead of hours.
Frequently asked questions
Can visitors fix a 503 error themselves?
No, a 503 is a server-side error, so visitors cannot fix it. They can wait a few minutes and reload the page, or try a private browser window to rule out a cached error page. If the error stays, only the site owner or host can fix it.
Does a 503 error hurt SEO?
A short 503 does little harm, because search engines treat it as temporary and keep the indexed pages. Google says a 503 is the right status for a brief outage. If the same URLs return 503 for multiple days, Google may drop them from its index, so fix the cause fast.
How long does WordPress maintenance mode last?
A normal update takes seconds to a few minutes, and WordPress removes the .maintenance file when the update ends. The core check treats maintenance mode as over once the timestamp inside the file is 10 minutes old. If the message lasts far longer, the update failed or another cause is behind the 503.
Why does my site show a 503 only during traffic spikes?
A traffic spike can use up every PHP worker or hit a memory, CPU, or connection limit, so new requests get a 503 instead of a page. Check your host resource graphs for the time of the spike, then look at caching, worker counts, and your plan limits to raise capacity.
Is a 503 error the same as the site being down?
Not quite. A 503 means the server answered the request but refused to serve the page right now, which is different from a server that does not answer at all. The site is still reachable, and the error is temporary, so the page should return once the cause clears.
Should I restore a backup to fix a 503 error?
Only if the 503 started right after a bad update and nothing else explains it. A backup can undo a faulty plugin or theme change. It will not help if the cause is server limits, overload, or a stuck maintenance file, so find the cause in the debug log first.
Sources
- 503 Service Unavailable MDN Web Docs
- 502 Bad Gateway MDN Web Docs
- Error 503: service temporarily unavailable Cloudflare Support docs
- Debugging in WordPress WordPress.org
- Editing wp-config.php Developer.WordPress.org
- How HTTP status codes affect Google's crawlers Google Search Central
Is your product missing, or something out of date?
Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.
Thanks — we review requests within 3 business days.
