HAProxy answers 503 "No server is available to handle this request"
503 Service UnavailableShort answer
HAProxy sends 503 when it has no server to give a request to. Ask the stats socket for the server status first. Servers marked DOWN usually fail their health check; a frontend with no matching backend, a server put into maintenance, and a full queue that times out are the other documented causes.
Fix it fast
1Find out which cause you have
Ask the running HAProxy for the state of every server. The socket path comes from the stats socket line in the global section.
echo "show servers state" | sudo socat /var/run/haproxy.sock stdio2Match what you see, then jump to its fix
- 1
status DOWN for each server in the stats outputEvery server in the backend is DOWN because its health check failsFix - 2
the frontend has use_backend rules and no default_backend; servers in the stats are healthyNo backend was selected for the requestFix - 3
status MAINT in the stats output while the application itself is healthyThe server was put into maintenance by hand or by a scriptFix - 4
503s during bursts only, with servers UPRequests waited in the queue longer than timeout queueFix
- 1
What does the error look like?
503 Service UnavailableNo server is available to handle this request.
Cause 1 of 4
Every server in the backend is DOWN because its health check fails
1Check
With check alone HAProxy only opens a TCP connection. With option httpchk it sends a real request, by default OPTIONS / over HTTP/1.0, and only 2xx or 3xx answers count as healthy. A backend that rejects OPTIONS, wants a Host header, or listens on another port fails the check. Test the same request by hand.
curl -i -X OPTIONS http://10.0.0.11:8080/
grep -n -E "httpchk|server " /etc/haproxy/haproxy.cfg2Fix
Point the check at a URL that returns 200 and send the Host header the backend expects. Use the server's real port in the server line.
backend app
option httpchk GET /health HTTP/1.1
http-check send hdr Host app.example.com
server web1 10.0.0.11:8080 check
server web2 10.0.0.12:8080 check3Verify
Validate the file, reload, and read the server status again.
sudo haproxy -c -f /etc/haproxy/haproxy.cfg
sudo systemctl reload haproxy
echo "show servers state" | sudo socat /var/run/haproxy.sock stdioConfirmed by docs.haproxy.org
Cause 2 of 4
No backend was selected for the request
1Check
When no use_backend condition matches and the frontend has no default_backend, HAProxy uses no server and returns 503.
grep -n -E "^(frontend|backend|listen)|use_backend|default_backend" /etc/haproxy/haproxy.cfg2Fix
Add a default_backend that catches everything the rules do not, or correct the ACL so the request matches a rule.
frontend www
bind :80
use_backend api if { path_beg /api }
default_backend app3Verify
Validate, reload and request a path that no rule matches.
sudo haproxy -c -f /etc/haproxy/haproxy.cfg
curl -i http://127.0.0.1/Confirmed by docs.haproxy.org
Cause 3 of 4
The server was put into maintenance by hand or by a script
1Check
disable server on the runtime socket marks a server DOWN for maintenance and stops its checks until it leaves that state.
echo "show stat" | sudo socat /var/run/haproxy.sock stdio | cut -d, -f1,2,18 | column -s, -t2Fix
Re-enable the server on an admin-level socket; this also turns its checks back on.
echo "enable server app/web1" | sudo socat /var/run/haproxy.sock stdio3Verify
The status column changes from MAINT to UP once a check passes.
echo "show servers state app" | sudo socat /var/run/haproxy.sock stdioConfirmed by docs.haproxy.org
Cause 4 of 4
Requests waited in the queue longer than timeout queue
1Check
When a server's maxconn is reached, extra requests wait in a queue. Past timeout queue the request is dropped and a 503 is returned. If timeout queue is unset, the connect timeout is used.
grep -n -E "maxconn|timeout" /etc/haproxy/haproxy.cfg2Fix
Raise the server's maxconn if the backend can take more, or lengthen timeout queue to what clients can accept. Adding servers is the real fix for sustained load.
backend app
timeout queue 30s
server web1 10.0.0.11:8080 check maxconn 2003Verify
Validate and reload, then repeat the burst that failed.
sudo haproxy -c -f /etc/haproxy/haproxy.cfg
sudo systemctl reload haproxyConfirmed by docs.haproxy.org
How do I stop it coming back?
- Give each backend a health-check URL that checks the application, and send the Host header it needs.
- Always set default_backend on a frontend that uses use_backend rules.
- Alert on servers leaving UP, so an empty backend is found before users see 503.
- Set maxconn per server to what it can really carry, and size timeout queue on purpose.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Servers
A Let's Encrypt certificate did not renew with Certbot
Type: connection ... Timeout during connect (likely firewall problem)
Run sudo certbot renew --dry-run and read the Type and Detail lines.
6 causes, each with a fixServers
curl cannot connect to port 80 or 443 on a server running nginx
CURLE_COULDNT_CONNECT (7): Failed to connect() to host or proxy
Exit code 7 means the TCP connection itself failed, before any HTTP happened.
3 causes, each with a fixServers
Django returns a 500 behind Gunicorn and the traceback is nowhere
The traceback shows locally with runserver but not under Gunicorn
With DEBUG set to False, Django's default logging does not print errors to the console.
2 causes, each with a fixServers
Your website on a Google Compute Engine VM times out on port 80
The site works with curl on the VM but not from outside
A timeout, as opposed to a refusal, usually means a firewall dropped the packets.
3 causes, each with a fixServers
Gunicorn rejects a request with "Error parsing headers: limit request headers fields size"
Error parsing headers: 'limit request headers fields'
Gunicorn caps the size of one header field at 8190 bytes and the number of headers at 100 by default.
2 causes, each with a fixServers
A Next.js static export works by clicking links but gives 404 on refresh or deep links
The home page loads, but a direct link to /blog/post-1 returns 404
A static export writes one HTML file per route, such as about.html.
3 causes, each with a fix