How to Fix Nginx Proxy Buffer Error

In this tutorial, you'll learn about How to Fix Nginx Proxy Buffer Error. We cover key concepts, practical examples, and best practices.

Nginx returns 502 Bad Gateway or upstream sent too big header while reading response header from upstream — the proxy buffer size is too small to hold the upstream server's response headers or body.

The Problem

2026/06/24 10:00:00 [error] upstream sent too big header while reading
response header from upstream, client: 10.0.0.1, server: example.com,
request: "GET /api/data HTTP/1.1", upstream: "http://10.0.0.2:3000"

Step-by-Step Fix

Step 1: Increase proxy buffer sizes

location /api/ {
    proxy_pass http://backend:3000;

    # Increase buffer sizes
    proxy_buffers 8 16k;
    proxy_buffer_size 32k;
    proxy_busy_buffers_size 64k;
}

Step 2: Disable buffering for streaming

location /stream/ {
    proxy_pass http://streaming-backend:3000;
    proxy_buffering off;
    proxy_cache off;
    proxy_set_header X-Accel-Buffering no;
}

Step 3: Check backend response headers

curl -I http://backend:3000/api/data
# Check the size of Set-Cookie, Location, and custom headers

Step 4: Configure response header limits on the backend

# If you control the backend
large_client_header_buffers 4 32k;

Step 5: Tune for specific use cases

# For APIs with large responses
location /api/ {
    proxy_buffering on;
    proxy_buffer_size 4k;
    proxy_buffers 16 16k;
    proxy_max_temp_file_size 0;
}

Prevention Tips

• Set proxy_buffer_size to at least 8k for modern apps
• Start with proxy_buffers 8 16k and monitor errors
• Disable buffering for Server-Sent Events and WebSocket
• Monitor backend response header sizes periodically

Common Mistakes with proxy buffer

1. Forgetting that lazy evaluation defers computation until the value is forced, causing space leaks with unevaluated thunks
2. Using return to exit a function early instead of wrapping a pure value in the monad
3. Mixing let bindings with <- bindings in do notation, producing type errors

These mistakes appear frequently in real-world NGINX code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ