HTTP 503 Service Unavailable — server overloaded or under maintenance

What causes this error

A 503 response means the server is reachable at the network level but cannot process the request right now. Common causes: the application process crashed or is restarting; a load balancer has no healthy backend targets; the server hit a connection pool limit (database connections, worker threads, file descriptors); a deployment is rolling and all old pods terminated before new ones passed health checks; a rate limiter or circuit breaker activated; or the server is in scheduled maintenance mode. Unlike a 500 (internal error), a 503 explicitly signals the condition is temporary.

How to fix it

1. 01

   step 1

   Check if the application process is running

   The most common cause is simply that the app isn't running. Check process status, memory usage, and recent crash logs.

   # Node.js / PM2
   pm2 status
   pm2 logs --lines 50
   
   # Systemd service
   systemctl status myapp
   journalctl -u myapp --since '5 minutes ago'
   
   # Docker
   docker ps -a | grep myapp
   docker logs myapp --tail 50

   Copy
2. 02

   step 2

   Check load balancer / reverse proxy health

   If you use Nginx, HAProxy, or a cloud load balancer, the 503 often comes from the proxy — not the app. Look for 'no live upstreams' or 'upstream prematurely closed connection' in proxy logs.

   # Nginx upstream check
   tail -100 /var/log/nginx/error.log | grep -i 'upstream\|502\|503'
   
   # AWS ALB — check target group health
   aws elbv2 describe-target-health \
     --target-group-arn arn:aws:elasticloadbalancing:...
   
   # HAProxy stats
   echo 'show stat' | socat unix:/var/run/haproxy.sock -

   Copy
3. 03

   step 3

   Check resource exhaustion (connections, memory, file descriptors)

   503s spike when the server runs out of a finite resource. Database connection pools, worker threads, and OS file descriptor limits are the usual suspects.

   # Check open connections to your DB
   psql -c "SELECT count(*) FROM pg_stat_activity;"
   
   # Check OS file descriptor limit vs usage
   ulimit -n
   ls /proc/$(pgrep -f myapp)/fd | wc -l
   
   # Check memory
   free -m
   top -bn1 | head -20

   Copy
4. 04

   step 4

   Handle rolling deployments properly

   During a deployment, old pods terminate before new ones are ready. Configure your orchestrator to keep at least one old pod alive until a new pod passes its health check.

   # Kubernetes — ensure zero-downtime deploys
   apiVersion: apps/v1
   kind: Deployment
   spec:
     strategy:
       type: RollingUpdate
       rollingUpdate:
         maxUnavailable: 0
         maxSurge: 1
     template:
       spec:
         containers:
         - name: app
           readinessProbe:
             httpGet:
               path: /health
               port: 8080
             initialDelaySeconds: 5
             periodSeconds: 5

   Copy

How to verify the fix

• curl -sI https://your-domain.com returns 200 (not 503).
• Load balancer target group shows all targets as 'healthy'.
• Application logs show no OOM kills or connection pool exhaustion.
• A rolling deployment completes without any 503 responses to real users.