How I Traced Intermittent 502 Errors on a WooCommerce Store to Nginx Buffer Misconfiguration

A client running a homeware WooCommerce store reported that some customers were getting 502 Bad Gateway errors at checkout. Not all customers, not every time — just often enough to cost them sales. Their hosting company had shrugged and suggested "upgrading to a bigger plan." The server had 8GB of RAM and was barely breaking a sweat. This wasn't a resource problem.

The Pattern Nobody Could Pin Down

The 502 errors were maddening because they were inconsistent. Most page loads were fine. The homepage, product pages, category pages — all fast, all reliable. But checkout would occasionally throw a 502. The WordPress admin dashboard did it too, especially the WooCommerce orders page. The client had been chasing this for weeks, disabling plugins one by one, switching themes, clearing caches. Nothing helped.

The first thing I did was stop guessing and start reading logs.

Finding the Real Error

The server was running Ubuntu 22.04 with Nginx as a reverse proxy to PHP 8.2-FPM. I pulled up the Nginx error log:

tail -200 /var/log/nginx/error.log | grep "502"

Dozens of lines, all with the same message:

upstream sent too big header while reading response header from upstream

That's not a generic "something went wrong" error. That's Nginx telling you exactly what happened: PHP-FPM sent back a response with headers larger than Nginx was willing to accept. Nginx couldn't buffer them, so it dropped the connection and returned a 502 to the browser.

Why WooCommerce Triggers This

Nginx allocates a fixed buffer to read the response headers from PHP-FPM before it starts streaming the body to the client. The default fastcgi_buffer_size is typically 4KB (one memory page). That sounds generous until you count what WordPress and WooCommerce actually send back in their response headers.

I inspected the response headers on a checkout page request by a logged-in admin user with items in the cart:

curl -sI -b "wordpress_logged_in_abc=admin%7C...;
  woocommerce_items_in_cart=1;
  woocommerce_cart_hash=a1b2c3d4e5;
  wp_woocommerce_session_xyz=user123%7C..." \
  https://example.com/checkout/ 2>&1 | wc -c

The response headers alone were over 6KB. Here's what was contributing:

• WordPress authentication cookies — wordpress_logged_in_*, wordpress_sec_* (long hashed values, often 200-400 bytes each)
• WooCommerce session cookies — wp_woocommerce_session_* with encoded session data
• WooCommerce cart cookies — woocommerce_items_in_cart, woocommerce_cart_hash
• Security headers — Content-Security-Policy, X-Frame-Options, Strict-Transport-Security (the CSP header alone was 800 bytes on this site)
• Plugin-set headers — a GDPR consent plugin was setting two additional cookies per response
• Cache control headers — Surrogate-Control, X-Cache-Status, various Cache-Control directives

Any single category was fine. Combined, they blew past the 4KB default buffer. The reason checkout was hit hardest is that it's where all these cookies converge: the user is logged in (WordPress auth cookies), has items in their cart (WooCommerce cart cookies), has an active session (WooCommerce session cookie), and the GDPR plugin is setting consent cookies. The admin dashboard had the same problem because admin users carry the full set of authentication cookies.

Guest users browsing product pages? Minimal cookies, small headers, no problem. That's why the errors were intermittent — they only hit users with enough accumulated cookie state.

The Fix

The solution is straightforward once you know the cause. I edited the Nginx configuration for the site's server block:

location ~ \.php$ {
    # ...existing fastcgi_pass, fastcgi_index, etc...

    # Buffer for reading the first part of the response (headers)
    # Default is typically 4k — too small for WooCommerce + auth cookies
    fastcgi_buffer_size 32k;

    # Buffers for reading the rest of the response body
    # Default is 8 buffers of 4k (32k total)
    fastcgi_buffers 16 16k;

    # Maximum size of buffers that can be busy sending to the client
    # while simultaneously reading more from the upstream
    fastcgi_busy_buffers_size 32k;

    # ...rest of existing config...
}

The critical directive is fastcgi_buffer_size. This single buffer holds the entire response header from PHP-FPM. If the headers don't fit, Nginx immediately returns a 502. Setting it to 32k gives plenty of headroom for WordPress's cookie-heavy responses.

The fastcgi_buffers directive controls how Nginx buffers the response body. The default of 8 4k (32KB total) is often fine for small pages, but WooCommerce admin pages can generate large HTML responses. 16 16k (256KB total) handles this comfortably.

After editing the config, I tested and reloaded:

nginx -t && systemctl reload nginx

Verifying the Fix

I needed to confirm the 502 errors were gone, not just hidden. First, I checked the Nginx error log for the specific error:

# Watch the error log in real time while testing
tail -f /var/log/nginx/error.log | grep "too big header"

Then I ran through the full customer journey: browse products, add to cart, go to checkout, complete an order. I did this both as a guest and as a logged-in admin (where cookies are largest). No 502 errors. The Nginx error log was clean.

I also checked the buffer usage wasn't wasteful. Nginx lets you see if responses are being written to temporary files instead of handled in memory:

grep "buffered" /var/log/nginx/error.log

No hits — all responses were fitting comfortably within the new buffer sizes. The 32KB allocation per connection is negligible on a server with 8GB of RAM, even under heavy load.

The Second Problem: Timeout on Checkout Submit

While I was testing, I noticed a related issue. On a test order with a particularly slow payment gateway callback, the checkout submission returned a 504 Gateway Timeout after 30 seconds. The default fastcgi_read_timeout was cutting the connection before PHP-FPM finished processing the payment.

For WooCommerce stores, payment processing can legitimately take 30-60 seconds when the gateway is slow or retrying. I added:

location ~ \.php$ {
    # ...buffer settings from above...

    # Default is 60s, but payment gateway callbacks can be slow
    fastcgi_read_timeout 300;

    # Matching PHP-FPM and php.ini settings:
    # php.ini: max_execution_time = 300
    # php-fpm pool: request_terminate_timeout = 300
}

The key is that fastcgi_read_timeout, PHP-FPM's request_terminate_timeout, and PHP's max_execution_time should be aligned. If Nginx gives up before PHP finishes, the customer sees a 504 even though the payment might still be processing in the background — a recipe for duplicate charges when the customer retries.

My Recommended Nginx Configuration for WooCommerce

After tuning dozens of WooCommerce servers, here's the FastCGI configuration block I start with:

location ~ \.php$ {
    fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    fastcgi_index index.php;
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;

    # Buffer sizing — handles WordPress + WooCommerce cookie-heavy responses
    fastcgi_buffer_size 32k;
    fastcgi_buffers 16 16k;
    fastcgi_busy_buffers_size 32k;

    # Timeout — long enough for payment gateway processing
    fastcgi_read_timeout 300;
    fastcgi_connect_timeout 60;
    fastcgi_send_timeout 300;

    # Don't buffer large responses to temp files unless necessary
    fastcgi_max_temp_file_size 0;
}

Adjust the fastcgi_pass socket path to match your PHP-FPM version. If you're running PHP-FPM on a TCP port instead, replace the socket path with 127.0.0.1:9000 or whatever port you've configured.

Why Default Configs Are Almost Always Wrong for WooCommerce

This is a pattern I see constantly across the 70+ sites I manage. Nginx ships with conservative defaults designed for simple applications. WordPress — especially WooCommerce — is not a simple application. It sets numerous cookies, generates large response headers, and runs PHP scripts that can legitimately take minutes when processing payments or running background tasks.

Most managed hosting platforms have already tuned these values. But if you're running your own VPS with CloudPanel, cPanel, or a manual Nginx setup, the defaults are probably still in place. I've written before about PHP-FPM worker exhaustion being another default-config problem — and this is in the same category. You won't notice until a customer's checkout fails on a Friday afternoon and you're left wondering why your "big enough" server is returning 502s.

If this kind of server-level tuning isn't something you want to deal with, that's exactly what WordPress server management is for.

The fix takes five minutes. The debugging takes five hours — unless you know to check the Nginx error log first.

---

Stop Firefighting. Start Maintaining.

I manage 70+ WordPress sites for agencies and businesses. Whether you need ongoing maintenance, emergency support, or a one-off performance fix — I can help.

View Maintenance Plans Get in Touch