Nginx Client Body Too Large Reverse Proxy

The Incident (What Does the Error Mean?)

You will see this in /var/log/nginx/error.log:

2024/01/15 03:42:17 [error] 1234#1234: *5678 client intended to send too large body: 8388608 bytes, 
client: 203.0.113.45, server: api.example.com, request: "POST /api/v2/upload HTTP/1.1", 
host: "api.example.com"

And the client receives:

HTTP/1.1 502 Bad Gateway

or in some proxy chain configurations:

HTTP/1.1 413 Request Entity Too Large

Immediate consequence: Nginx has already closed the connection. The upstream (Node.js, Gunicorn, uWSGI, a microservice) never received the request. Any retry logic in the client will hammer Nginx again with the same result. File uploads, large JSON payloads, multipart form data, and webhook bodies with large event arrays are the most common triggers.

The Attack Vector / Blast Radius

This is a misconfiguration-driven availability failure, not a security exploit — but the blast radius is significant:

1. Silent 502 storm: Depending on your upstream health check config, repeated 502s from Nginx can cause your load balancer (ALB, HAProxy, Cloudflare) to mark the backend as unhealthy and pull it from rotation. A single large-payload endpoint can take down routing for the entire service.

2. Asymmetric limit mismatch: The most dangerous variant is when client_max_body_size is set in the http {} block but overridden (or forgotten) in a nested location {} block. Developers raise the global limit, test it, and ship — then a new location /api/internal/ block added six months later inherits the default 1MB cap. Production breaks only for that route.

3. Proxy chain amplification: In a multi-layer proxy setup (CDN → Nginx → App Server), each layer has its own body size limit. If Nginx passes the request but your uWSGI or Gunicorn has a lower --limit-request-line or MAX_CONTENT_LENGTH, you get a 502 from Nginx wrapping a 413 from the app — doubly confusing to debug.

4. DoS surface (inverse): Setting client_max_body_size 0 (unlimited) to "fix" this is a denial-of-service vector. An attacker can stream arbitrarily large bodies, exhausting disk buffers under /var/cache/nginx and RAM. Never set to 0 on a public-facing endpoint.

Prevention in CI/CD

This class of misconfiguration is 100% preventable with static analysis in your pipeline.

1. Nginx Config Linting with `gixy`

gixy is a static analysis tool for Nginx configs. Add it to your CI:

# .github/workflows/nginx-lint.yml
- name: Lint Nginx config with gixy
  run: |
    pip install gixy
    gixy /etc/nginx/nginx.conf

gixy will flag missing client_max_body_size overrides and dangerous proxy_pass configurations.

2. Checkov for IaC (Terraform/Helm-deployed Nginx)

If you deploy Nginx via Helm or Terraform-managed ConfigMaps:

checkov -d ./helm/nginx --framework kubernetes

Write a custom Checkov check:

# checkov/custom_checks/nginx_body_size.py
from checkov.common.models.enums import CheckResult, CheckCategories
from checkov.kubernetes.checks.resource.base_spec_check import BaseK8Check

class NginxBodySizeCheck(BaseK8Check):
    def __init__(self):
        name = "Ensure nginx ConfigMap sets client_max_body_size explicitly"
        id = "CKV_CUSTOM_NGINX_001"
        super().__init__(name=name, id=id, 
                         categories=[CheckCategories.GENERAL_SECURITY],
                         supported_entities=['ConfigMap'])

    def scan_spec_conf(self, conf):
        data = conf.get('data', {})
        nginx_conf = data.get('nginx.conf', '')
        if 'client_max_body_size' in nginx_conf:
            return CheckResult.PASSED
        return CheckResult.FAILED

3. Integration Test with `curl` in Your Pipeline

Don't wait for production to discover the limit. Add a smoke test:

#!/bin/bash
# ci/test_upload_limit.sh
# Generate a 50MB test file and assert Nginx accepts it
dd if=/dev/urandom of=/tmp/test_payload.bin bs=1M count=50 2>/dev/null

HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  -X POST \
  -H "Content-Type: application/octet-stream" \
  --data-binary @/tmp/test_payload.bin \
  https://staging-api.example.com/api/v2/upload)

if [ "$HTTP_STATUS" == "413" ] || [ "$HTTP_STATUS" == "502" ]; then
  echo "FAIL: Upload rejected with $HTTP_STATUS — check client_max_body_size"
  exit 1
fi
echo "PASS: Upload accepted with $HTTP_STATUS"

4. OPA/Conftest Policy for Nginx ConfigMaps

# policies/nginx_body_size.rego
package nginx

deny[msg] {
  input.kind == "ConfigMap"
  nginx_conf := input.data["nginx.conf"]
  not contains(nginx_conf, "client_max_body_size")
  msg := sprintf("ConfigMap '%v' nginx.conf is missing client_max_body_size directive", [input.metadata.name])
}

Run in CI:

conftest test ./k8s/nginx-configmap.yaml --policy ./policies/