Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

Gunicorn rejects a request with "Error parsing headers: limit request headers fields size"

ErrorError 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.

  • Applies to Gunicorn 23, nginx 1.26, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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-pager
  2. 2Match what you see, then jump to its fix

    1. 1limit request headers fields sizeOne header, usually Cookie or Authorization, is bigger than limit_request_field_sizeFix
    2. 2limit request headers fields (no word size after it)The request carries more than limit_request_fields headersFix

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 = 16380

3Verify

Restart Gunicorn and repeat the request that failed.

sudo systemctl restart gunicorn
sudo journalctl -u gunicorn -n 10 --no-pager

Confirmed by gunicorn.org

Did this fix it?

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.py

2Fix

Remove headers nothing reads, or raise the count. Gunicorn does not accept a value above 32768.

# gunicorn.conf.py
limit_request_fields = 200

3Verify

Restart Gunicorn and replay the request.

sudo systemctl restart gunicorn

Confirmed by gunicorn.org

Did this fix it?

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

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.