413 Request Entity Too Large — Fix Nginx Upload Limits

Your users hit 'Upload' and instantly get a 413 Request Entity Too Large error. No progress bar, no partial save, no helpful message — just a flat rejection. The frustrating part is that your application logs show nothing at all, because the request never reached your code. The web server sitting in front of your app killed it at the door.

This error shows up the moment real users do real things: a seller uploads 22 MB of product photos, a patient attaches a scanned PDF to a support ticket, an API client POSTs a 5 MB JSON payload. Everything worked in development because test files are tiny. Production files aren't.

The trap is that there's rarely one limit. Nginx has its default 1 MB cap, your CDN may enforce 30 MB, your Kubernetes ingress has its own annotation, and your app framework adds yet another ceiling on top. Raising just one of them moves the failure to the next hop instead of fixing it.

By the end of this article you'll know how to trace a 413 to the exact hop that rejected it, compare Content-Length against each configured limit, and raise every layer consistently. You'll also learn when raising the limit is wrong — and chunked or direct-to-S3 uploads are the real answer.

How Nginx Enforces client_max_body_size Before Your App Runs

Nginx checks the request body size before it does anything else useful — before proxying, before auth, before your upstream sees a single byte. The directive is client_max_body_size, and its default is 1m. That default was chosen in an era of small form posts, and it silently governs every file upload, every large JSON payload, and every multipart form that passes through the server.

The check happens against the Content-Length header first. If the declared length exceeds the limit, Nginx returns 413 immediately and logs 'client intended to send too large body' to error.log. If the client uses chunked transfer encoding with no Content-Length, Nginx reads the body as it streams and aborts with 413 the moment the accumulated bytes cross the limit. Either way, the upstream gets nothing — not a truncated body, not an error callback, just silence.

Scope matters enormously. The directive is valid in http, server, and location contexts, and the most specific block wins. A 60m in the http block with a 2m in one location means that location enforces 2m. Most production incidents come from exactly this: someone raised the global value while a location block for /api/uploads kept a stricter one, or vice versa. Always verify the effective value with nginx -T and read which block actually matches your upload path. After reloading, re-run the curl bracket test — the size that failed before should now pass, proving that location block (not some other hop) owned the rejection.

# Global default stays strict — internal endpoints keep 1m protection
http {
    client_max_body_size 1m;
}

server {
    listen 443 ssl;
    server_name app.example.com;

    # Public upload endpoint: match this to the app framework cap
    location /api/uploads {
        client_max_body_size 60m;
        client_body_timeout 60s;
        proxy_pass http://app_upstream;
    }

    # Everything else keeps the tight default
    location /api/ {
        proxy_pass http://app_upstream;
    }
}

# After editing, verify the effective value per block:
# nginx -t && systemctl reload nginx
# nginx -T 2>/dev/null | grep -B 5 'client_max_body_size'

Confirm It: Content-Length Versus the Limit in error.log

Don't guess which layer rejected the upload — prove it. The signature of an Nginx-side 413 is unmistakable: a line in error.log reading 'client intended to send too large body' with the exact byte count. That line also tells you the declared size, so you can compare it directly against your configured limit and see the gap in one glance.

Reproduce the failure deliberately with curl and a test file of known size. Use --data-binary with a file just over your suspected limit and watch for HTTP 413 in the response headers. The -v flag shows you the Content-Length curl sent, which removes all doubt about what the client declared. If the app works for a 900 KB file and fails for a 1.1 MB file, you've bracketed a 1m limit without reading a single config file.

Correlate timestamps next. Match the 413 responses in access.log (status 413, bytes sent, request path) against the error.log rejection lines and your support tickets. When all three agree, you've got an airtight diagnosis: which path, what size, and which limit fired. This takes ten minutes and prevents the classic multi-hour detour into debugging application code that never ran. Save the bracket results (pass/fail per megabyte) in the incident ticket — they become the regression test you re-run after every future limit change.

# 1. Find Nginx-side rejections with exact byte sizes
sudo grep 'client intended to send too large body' /var/log/nginx/error.log | tail -20

# 2. Correlate with 413s in the access log (path + status + size)
sudo awk '$9 == 413 {print $4, $7, $9, $10}' /var/log/nginx/access.log | tail -20

# 3. Show the effective limit for every block
sudo nginx -T 2>/dev/null | grep -B 3 'client_max_body_size'

# 4. Reproduce with a known-size file and watch the status code
dd if=/dev/urandom of=/tmp/test-2m.bin bs=1M count=2
curl -v -X POST https://app.example.com/api/uploads \
  -H 'Content-Type: application/octet-stream' \
  --data-binary @/tmp/test-2m.bin 2>&1 | grep -iE '< HTTP|content-length'

# 5. Bracket the limit: binary-search the failing size
for mb in 1 2 5 10 60; do
  dd if=/dev/urandom of=/tmp/t.bin bs=1M count=$mb 2>/dev/null
  code=$(curl -s -o /dev/null -w '%{http_code}' -X POST https://app.example.com/api/uploads --data-binary @/tmp/t.bin)
  echo "${mb}MB -> $code"
done

Proxy Chains: Every Hop Has Its Own Limit

Fixing Nginx alone often just moves the 413 one hop closer to the user. A typical production path — browser to CDN, to cloud load balancer, to Kubernetes ingress, to Nginx sidecar, to app — has up to five independent body-size limits, and the effective cap is the smallest of all of them. Each layer returns its own flavor of rejection, which is why the error page changes shape as you fix layers one by one.

Cloud load balancers are the sneakiest hop because their limits aren't always configurable. Some ALB configurations cap certain request paths around 30 MB, and CDN free tiers commonly enforce 100 MB per request. Kubernetes ingress controllers add their own: the NGINX ingress uses the client-max-body-size annotation (default 1m, mirroring Nginx), and each Ingress resource can override it independently. If your team fixed the Nginx Deployment but uploads route through an ingress with the default annotation, nothing changed for real traffic.

Debug the chain by peeling layers. Bypass the CDN by curling the load balancer directly, bypass the LB by hitting the ingress, bypass the ingress with port-forward straight to the pod. The first hop that stops returning 413 as you peel inward is the hop whose limit was blocking you. Document every hop's limit in one runbook table afterward — future-you will thank present-you at 2 AM.

# Peel the chain from the inside out — first hop that succeeds is below the blocker
# 1. Direct to pod (bypasses CDN, LB, ingress, sidecar Nginx)
kubectl port-forward deploy/app 8080:8080 &
curl -s -o /dev/null -w 'direct-to-pod: %{http_code}\n' -X POST http://localhost:8080/api/uploads --data-binary @/tmp/test-20m.bin

# 2. Through ingress Nginx only (bypasses CDN + cloud LB)
curl -s -o /dev/null -w 'via-ingress: %{http_code}\n' -X POST https://internal.example.com/api/uploads --data-binary @/tmp/test-20m.bin

# 3. Full public path (every hop)
curl -s -o /dev/null -w 'public-url: %{http_code}\n' -X POST https://app.example.com/api/uploads --data-binary @/tmp/test-20m.bin

# 4. Check the ingress annotation that most teams forget
kubectl get ingress app -o jsonpath='{.metadata.annotations}' | tr ',' '\n' | grep -i body

# 5. Set it per-Ingress when the global default is too strict
kubectl annotate ingress app nginx.ingress.kubernetes.io/proxy-body-size=60m --overwrite

Express and Multer Caps That Reject After Nginx Passes

Once Nginx allows the body through, your Node.js framework gets its own vote. Express's built-in JSON parser defaults to a 100 KB limit — far smaller than most teams expect — so a 2 MB API payload sails through a 60m Nginx config and then dies inside express.json() with a 413 PayloadTooLargeError. Multipart uploads go through Multer instead, which enforces its own fileSize cap per file, and exceeding it produces an error your handler must catch explicitly or the client sees a hung connection.

The failure mode here is confusing because it looks like your route code ran and threw. It didn't — the body-parsing middleware rejected the request before your handler executed. The tell is the error shape: entity.too.large from body-parser, or Multer's LIMIT_FILE_SIZE code. Log these distinctly from business-logic errors so your dashboards separate 'client sent too much' from 'our code broke'.

Match these caps to the Nginx location value deliberately, with Nginx slightly larger. If Nginx allows 60m but Multer allows 50m, Multer's structured error reaches the client with a message you control. If it's reversed, Nginx's bare 413 page wins and your careful error handling never fires. Keep both numbers as named constants with comments referencing each other.

const express = require('express');
const multer = require('multer');

const app = express();
// Keep in sync with nginx `client_max_body_size 60m` on /api/uploads.
// Nginx stays slightly larger so the app returns structured errors.
const JSON_LIMIT = '50mb';
const FILE_LIMIT = 50 * 1024 * 1024;

app.use('/api', express.json({ limit: JSON_LIMIT }));
app.use('/api', express.urlencoded({ limit: JSON_LIMIT, extended: true }));

const upload = multer({
  dest: 'uploads/',
  limits: { fileSize: FILE_LIMIT, files: 5 },
});

app.post('/api/uploads', upload.array('files', 5), (req, res) => {
  res.json({ ok: true, count: req.files.length });
});

// Structured 413s instead of a hung connection or bare Nginx page
app.use((err, req, res, next) => {
  if (err.type === 'entity.too.large' || err.code === 'LIMIT_FILE_SIZE') {
    return res.status(413).json({ error: 'File too large — max 50 MB per file' });
  }
  next(err);
});

app.listen(3000, () => console.log('limits: json=%s file=%d', JSON_LIMIT, FILE_LIMIT));

Spring Multipart and Django Caps in JVM and Python Stacks

Spring Boot caps multipart uploads with two properties that work as a pair: max-file-size limits each individual file, while max-request-size caps the entire multipart request including all files plus form fields. The defaults are 1 MB per file and 10 MB per request — generous-looking until a user attaches three 4 MB scans and the 12 MB total blows past max-request-size. Exceeding either throws a MultipartException that Spring translates to a 500 unless you handle MaxUploadSizeExceededException explicitly, which turns an infrastructure limit into a misleading server-error alert.

Django's equivalent is DATA_UPLOAD_MAX_MEMORY_SIZE (2.5 MB default), which controls when uploaded data spills from memory to a temp file, plus DATA_UPLOAD_MAX_NUMBER_OF_FIELDS that rejects forms with too many fields. Django raises SuspiciousOperation for oversized payloads, and large file handling also depends on FILE_UPLOAD_MAX_MEMORY_SIZE. These defaults are tuned for small forms, not for document-heavy workflows, so any app accepting scans or media needs explicit values in settings.py.

The pattern is identical across stacks: find the framework's body cap, set it just under the proxy's cap, and convert the rejection into a clean 413 response with the actual limit in the message. Users who see 'max 50 MB per file' retry with a smaller file; users who see a bare error page file a support ticket.

# Spring Boot: keep both values just under nginx client_max_body_size 60m
spring:
  servlet:
    multipart:
      enabled: true
      max-file-size: 50MB        # per-file cap
      max-request-size: 55MB     # whole-request cap (files + form fields)
      file-size-threshold: 1MB   # spill to disk above this, protects heap

---
# Django equivalent in settings.py (shown here as YAML for comparison):
# DATA_UPLOAD_MAX_MEMORY_SIZE = 50 * 1024 * 1024
# FILE_UPLOAD_MAX_MEMORY_SIZE = 50 * 1024 * 1024
# DATA_UPLOAD_MAX_NUMBER_OF_FIELDS = 2000

# Spring: turn the rejection into a clean 413 with the limit in the message
# @ExceptionHandler(MaxUploadSizeExceededException.class)
# public ResponseEntity<?> tooLarge() {
#   return ResponseEntity.status(413).body(Map.of("error", "File too large - max 50 MB"));
# }

Stop Raising Limits: Chunked and Direct-to-S3 Uploads

Every limit increase buys headroom and sells reliability. Larger bodies mean longer proxy buffering, more memory per connection, slower client retries, and a bigger denial-of-service surface. Past roughly 10–50 MB per file, the correct fix stops being a bigger number and starts being a different architecture: chunked uploads or direct-to-object-storage uploads that bypass your proxy entirely.

Chunked uploads split the file in JavaScript (Blob.slice) into 5 MB parts, POST each part with a sequence number, and reassemble server-side. Each part stays far under every limit in the chain, failed parts retry individually instead of restarting a 2 GB transfer, and you get a progress bar for free. Libraries like tus and Uppy implement the resumable-upload protocol so you don't hand-roll reassembly and cleanup of orphaned parts.

Direct-to-S3 (or GCS/Azure Blob) goes further: your API returns a presigned URL, the browser PUTs the file straight to object storage, and your servers never touch the bytes. Nginx limits become irrelevant for payload data, bandwidth costs drop, and uploads scale without scaling your app tier. The app's only job is authorizing the URL and validating the result — which is exactly the separation that prevents the next 413 incident before it starts.

import boto3
from flask import Flask, request, jsonify

app = Flask(__name__)
s3 = boto3.client('s3')
BUCKET = 'uploads-prod'
# Small form posts still go through Nginx (60m cap); big files skip it entirely.
MAX_DIRECT_MB = 10

@app.route('/api/uploads/presign', methods=['POST'])
def presign():
    name = request.json['filename']
    size_mb = request.json['size_mb']
    if size_mb <= MAX_DIRECT_MB:
        return jsonify({'mode': 'direct-post', 'url': '/api/uploads'}), 200
    url = s3.generate_presigned_url(
        'put_object',
        Params={'Bucket': BUCKET, 'Key': f'raw/{name}',
                'ContentType': request.json.get('content_type', 'application/octet-stream')},
        ExpiresIn=900,  # 15-minute window to start the upload
    )
    return jsonify({'mode': 's3-direct', 'url': url, 'max_mb': 5000}), 200

@app.route('/api/uploads/complete', methods=['POST'])
def complete():
    # Client calls this after the S3 PUT succeeds; validate size + virus-scan here.
    key = request.json['key']
    head = s3.head_object(Bucket=BUCKET, Key=key)
    return jsonify({'ok': True, 'bytes': head['ContentLength']}), 200