Gunicorn rejects a request with "Error parsing headers: limit request headers fields size"
Error parsing headers: 'limit request headers fields size'Short answer
Gunicorn caps the size of one header field at 8190 bytes and the number of headers at 100 by default. A large cookie or bearer token breaks the first limit; many headers break the second. Raise limit_request_field_size or limit_request_fields in the Gunicorn config, or send less in the headers.
Fix it fast
1Find out which cause you have
Read the Gunicorn log. The last words of the message tell you which of the two limits was hit.
sudo journalctl -u gunicorn -n 30 --no-pager2Match what you see, then jump to its fix
What does the error look like?
Error parsing headers: 'limit request headers fields size'Error parsing headers: 'limit request headers fields'Invalid request from ip=127.0.0.1: limit request headers fields size
Cause 1 of 2
One header, usually Cookie or Authorization, is bigger than limit_request_field_size
1Check
The default for this limit is 8190 bytes for a single header field. Long JWTs and cookies that pile up (sessions, analytics, consent) pass it. Measure the headers a browser really sends in the request panel of its developer tools.
curl -s -o /dev/null -H "Cookie: $(head -c 9000 /dev/zero | tr '\0' a)" -w '%{http_code}\n' http://127.0.0.1:8000/2Fix
Trim what goes into the cookie or token. If it really must be larger, raise the limit in the Gunicorn config file. Gunicorn reads gunicorn.conf.py from the working directory by default, or the file given with -c.
# gunicorn.conf.py
limit_request_field_size = 163803Verify
Restart Gunicorn and repeat the request that failed.
sudo systemctl restart gunicorn
sudo journalctl -u gunicorn -n 10 --no-pagerConfirmed by gunicorn.org
Cause 2 of 2
The request carries more than limit_request_fields headers
1Check
Gunicorn limits how many headers one request may have, 100 by default, to protect against abuse. A client that sends hundreds of headers will reach it.
grep -n "limit_request" gunicorn.conf.py2Fix
Remove headers nothing reads, or raise the count. Gunicorn does not accept a value above 32768.
# gunicorn.conf.py
limit_request_fields = 2003Verify
Restart Gunicorn and replay the request.
sudo systemctl restart gunicornConfirmed by gunicorn.org
How do I stop it coming back?
- Keep sessions server-side and put only an ID in the cookie.
- Keep tokens short-lived and small instead of loading claims into them.
- Raise a limit only to the size you need; the defaults exist to stop abusive requests.
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
nginx answers 400 when a request header or cookie is too big
414 Request-URI Too Large (when the request line, not a header, is too long)
nginx rejects a request with 400 when a single header field, usually a cookie, does not fit in one header buffer.
2 causes, each with a fixServers
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
HAProxy answers 503 "No server is available to handle this request"
No server is available to handle this request.
HAProxy sends 503 when it has no server to give a request to.
4 causes, each with a fix