503 Service Unavailable

What this error means & how to recognize it

• The browser, API client, or monitoring tool reports 503 Service Unavailable or Service Temporarily Unavailable.
• The error appears during heavy traffic and clears when demand falls.
• The site remains unavailable after a CMS update or deployment because maintenance mode was not cleared.
• The error continues while a required database, cache service, or upstream API is unavailable.
• Only particular URLs, clients, request patterns, or backends receive 503 responses because of rate limiting, a WAF rule, routing, or an unhealthy load-balancer health check.
• Response headers or a proxy-generated error page indicate that the request may not have reached the application.

Root causes, ordered by likelihood

1. Server overload — CPU, memory, active connections, web-server workers, PHP-FPM workers, or database connections are exhausted by normal demand or a traffic spike.
2. Stuck maintenance mode — A CMS update or deployment enables a maintenance flag but does not remove it after an interruption. In WordPress, this may be an orphaned .maintenance file.
3. Unavailable required dependency — The application cannot reach a database, cache layer, or internal API needed to serve the request. The dependency may be running but inaccessible from the application host or network.
4. Intentional rate limiting or WAF behavior — A rate limiter or web application firewall may return 503 responses when traffic exceeds a threshold or matches a security rule.
5. Faulty load-balancer health check — A check may mark healthy backend instances unavailable because it uses the wrong path or expects the wrong response code.
6. Proxy or upstream configuration problem — A reverse proxy, CDN, or upstream service may generate the 503 before the application receives the request.

How to fix it

1. Identify which layer generated the 503

Check response headers and compare logs from the application, web server, reverse proxy, CDN or WAF, and load balancer. Determine whether the response came from the application or was generated before the request reached it. This prevents changing application settings when the blocking layer is elsewhere.

2. Check resource usage at the time of failure

Review CPU, memory, active connections, web-server workers, PHP-FPM workers if applicable, and database connections. Use read-only monitoring tools such as top or htop, hosting dashboards, and infrastructure monitoring to determine whether a limit was reached.

• If a resource was near capacity, treat the incident as an overload or capacity problem.
• If resource usage was normal, investigate maintenance state, dependencies, rate limits, WAF rules, and health checks.

3. Clear an incomplete maintenance state

For WordPress, confirm that the update has completed or that the site is authorized for maintenance, then connect through SFTP and check the site root for a file named .maintenance. If the update completed but this file remains, remove it and test the site again. Removing the file changes the site’s maintenance state, so do not do this during an active update or deployment.

Other platforms and deployment tools may use a flag file or environment variable. Check the update or deployment process to identify what enables maintenance mode and whether its cleanup step ran after an interrupted process.

4. Test dependencies from the application server

Confirm that the database, cache layer such as Redis or Memcached, and required internal services are running and reachable from the application server. Check for connection errors, authentication failures, timeouts, and service-log entries.

A dependency can be operational in general but unreachable from the specific application host because of network access, credentials, routing, or a service-level failure.

5. Address genuine overload

Identify the limiting resource before increasing any setting. The bottleneck may be CPU, memory, database connections, web-server connections, or PHP-FPM workers.

For short-term relief, reduce expensive work, increase a limit only when the host has sufficient spare capacity and the change is authorized, or add caching for suitable pages. For recurring demand, consider a CDN or cache layer and additional backend capacity rather than repeatedly raising limits.

6. Check rate limits, WAF rules, and load-balancer health checks

Review Nginx, Apache, CDN, or other proxy and security logs for rules that intentionally return 503 responses. Inspect health-check paths, expected status codes, and backend registration. If only particular URLs, clients, or backends fail, this evidence can distinguish traffic control or routing from a whole-site outage.

7. Verify the repair

Repeat the request that failed and check application, proxy, and dependency logs. Confirm that normal requests succeed and, where possible, test under a similar traffic level or time of day. Make sure the fix addresses the triggering condition rather than only clearing a temporary symptom.

Prevention & how to verify the fix

• Ensure deployment and update scripts remove maintenance flags in a cleanup or finally step, including after partial failures.
• Monitor CPU, memory, active connections, worker usage, and database connections, with alerts before capacity is exhausted.
• Cache suitable pages and database work so traffic spikes consume less backend capacity.
• Test load-balancer health checks against the correct path and expected response code.
• Review rate-limit and WAF changes so intentional 503 responses can be distinguished from service failures.
• Keep application, proxy, dependency, and infrastructure logs available for the same time range so failures can be correlated.
• After a fix, verify the site under conditions similar to those that triggered the original error.

Frequently asked questions