NGINX 500 internal server error caused by large JWT tokens

Hello Myra,

Thank you for posting your question on the Microsoft Windows Forum!

The error:

upstream sent too big header

typically occurs when the response headers returned by the upstream application exceed the default NGINX buffer limits. Large JWT tokens stored in headers or cookies are a common cause of this issue.

To resolve it, increase the buffer sizes in your NGINX configuration.

Recommended Configuration

Edit your NGINX configuration file and add or update the following settings:

proxy_buffer_size 128k;

proxy_buffers 4 256k;

proxy_busy_buffers_size 256k;

If the JWT token is being passed in request headers, you may also need:

large_client_header_buffers 4 64k;

Apply the Changes

1. Validate the configuration:

nginx -t

1. Reload NGINX:

nginx -s reload

or on Linux:

systemctl reload nginx

Additional Recommendation

While increasing the buffer size resolves the immediate issue, consider reviewing the JWT payload itself. Extremely large JWTs often indicate that too many claims, roles, or permissions are being stored in the token. Reducing token size can help improve performance and avoid similar header size issues in the future.

Verify the Fix

After applying the changes:

• Retry the request that was failing.
• Check the NGINX error log for new occurrences of:

upstream sent too big header

For additional reference:

https://nginx.org/en/docs/http/ngx_http_proxy_module.html

https://nginx.org/en/docs/http/ngx_http_core_module.html#large_client_header_buffers

I hope this answer has brought you useful information. If so, please click on Accept Answer. Doing so helps other community members identify useful solutions to similar issues.

Welcome to Microsoft Q&A!

Thank you for providing the details of your environment and for clearly describing the issue you're encountering.

Based on the behavior you have described, the error message: “upstream sent too big header while reading response header from upstream” typically indicates that the response headers returned by the upstream application exceed the buffer size that NGINX allocates for processing response headers. This is commonly seen in environments that use large JWT tokens, oversized cookies, SSO/OAuth authentication flows, or applications that generate lengthy redirect headers.

The reason why this occurs because by default, NGINX allocates a relatively small buffer for upstream response headers. When a JWT is passed in a cookie or response header, the combined header size can exceed the default buffer limit, causing NGINX to fail while reading the response header and return a 500 or 502 error.

This behavior has also been observed in internal investigations where the default 4 KB proxy_buffer_size was insufficient. Increasing the proxy buffer settings successfully resolved the issue in those cases.

I would like to recommend you resolution

To accommodate larger JWT tokens and response headers, increase the NGINX proxy buffer settings in the http, server, or location block.

Example:

http {
    proxy_buffer_size       16k;
    proxy_buffers           8 16k;
    proxy_busy_buffers_size 32k;
}

Alternatively, you can apply the configuration to a specific application endpoint:

location / {
    proxy_pass http://backend;
 
    proxy_buffer_size       16k;
    proxy_buffers           8 16k;
    proxy_busy_buffers_size 32k;
}

For environments where authentication tokens or cookies are particularly large, a larger buffer allocation may be appropriate:

proxy_buffer_size       32k;
proxy_buffers           8 32k;
proxy_busy_buffers_size 64k;

After making the changes, validate and reload the configuration:

nginx -t

nginx -s reload

For NGINX Ingress Controller (Kubernetes), if you are using the NGINX Ingress Controller, the buffer size can be increased through an ingress annotation:

metadata:
  annotations:
    nginx.ingress.kubernetes.io/proxy-buffer-size: "16k"

Note: Adding the proxy-buffer-size annotation effectively possible resolved failures caused by oversized response headers generated during authentication flows.

Additionally, while increasing the buffer size is the most common and immediate mitigation, you may also want to review the application's header usage to reduce the overall header footprint where possible:

• Minimize unnecessary JWT claims.
• Store session data server-side instead of embedding large amounts of data in cookies.
• Review Set-Cookie and Location headers for excessive length.
• Consider using shorter-lived or more compact tokens when supported by the application architecture.

In most cases, increasing proxy_buffer_size to 16 KB is sufficient. If the issue persists, you can try increasing the value to 32 KB and adjusting the related buffer settings accordingly.

If you find it useful, please click Accept Answer.

Thank you for choosing Microsoft Q&A.