🚨 OpenTelemetry Error Guide: '413 Request Entity Too Large' on OTLP/HTTP — Fix Oversized Payloads

Overview

This error appears when the OTLP/HTTP exporter posts a payload that is larger than the maximum body size the backend, gateway, or reverse proxy in front of it will accept. The server answers with HTTP 413 and the Collector logs the exporter failure:

error exporting items, request to https://otel.example.com/v1/traces responded with HTTP Status Code 413, Message=Request Entity Too Large

The proxy in front of the backend often logs the paired rejection so you can confirm where the cap lives:

2026/07/12 14:22:10 [error] 41#41: *8842 client intended to send too large body: 12582912 bytes, client: 10.0.0.11, request: "POST /v1/traces HTTP/1.1", host: "otel.example.com"

HTTP 413 means the exported request body exceeded a hard size limit somewhere on the path — the batch was never ingested, and it is dropped or retried depending on your queue configuration.

Symptoms

• Traces or metrics arrive during quiet periods but disappear during bursts, when batches grow larger.
• Collector logs repeat HTTP Status Code 413, Message=Request Entity Too Large on the otlphttp exporter.
• A reverse proxy (nginx, Envoy, ALB) or API gateway sits between the Collector and the backend.
• Larger services with high span-per-request counts fail while low-volume services succeed.
• Retries never clear the error because the batch is deterministically too big, not transiently rejected.

Common Root Causes

• Proxy body-size cap — nginx client_max_body_size (default 1m), Envoy, or an ALB enforces a maximum request body smaller than the batch.
• Backend ingest limit — the OTLP backend itself rejects payloads above a documented per-request byte limit.
• Oversized batches — send_batch_max_size is unset or too high, so the batch processor emits multi-megabyte requests.
• Compression disabled — the exporter sends uncompressed protobuf, inflating an otherwise acceptable batch several times over.
• Tail-heavy spans — large span attributes, events, or logs bodies bloat individual items so even small batches exceed the cap.
• Aggregated retries — a persistent queue replays a backlog as one giant request after an outage.

Diagnostic Workflow

Confirm which hop is returning the 413 by testing the backend directly, bypassing your Collector, with a trivially small then a large body:

# Small OTLP/HTTP probe — should return 200/partial success, not 413
curl -v -X POST https://otel.example.com/v1/traces \
  -H 'Content-Type: application/x-protobuf' \
  --data-binary @small-traces.pb

# Confirm the proxy's advertised limit
curl -sI https://otel.example.com/v1/traces | grep -i 'content-length\|server'

Cap the batch size and enable compression on the exporter so each request is smaller and denser. send_batch_max_size is the hard ceiling on items per export:

processors:
  batch:
    timeout: 5s
    send_batch_size: 512
    send_batch_max_size: 512   # hard cap on items per exported request

exporters:
  otlphttp:
    endpoint: https://otel.example.com
    compression: gzip          # shrink the wire payload before it hits the cap
    encoding: proto
    retry_on_failure:
      enabled: true
      initial_interval: 5s
      max_elapsed_time: 300s
    sending_queue:
      enabled: true
      num_consumers: 4
      queue_size: 5000

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlphttp]

If you control the proxy, raise its body limit to comfortably exceed your compressed batch. For nginx in front of the OTLP endpoint:

# /etc/nginx/conf.d/otel.conf
#   client_max_body_size 16m;
nginx -t && systemctl reload nginx
journalctl -u otelcol-contrib --since '10 min ago' | grep -i '413\|too large'

Example Root Cause Analysis

A checkout service emitted verbose spans with large SQL-statement attributes. Its Collector batched send_batch_size: 8192 with compression off and exported through an nginx proxy whose default client_max_body_size was 1m. During peak traffic a single batch serialized to ~12 MB, nginx rejected it, and the Collector logged HTTP Status Code 413, Message=Request Entity Too Large while dropping every peak-hour batch.

The fix had two parts. First, the exporter set compression: gzip and the batch processor was capped at send_batch_max_size: 512, which cut a typical request from ~12 MB to well under 1 MB on the wire. Second, nginx client_max_body_size was raised to 16m as headroom for outlier batches. After the change the 413s stopped, no peak-hour data was dropped, and retries were no longer needed because requests now fit the cap deterministically.

Prevention Best Practices

• Always set an explicit send_batch_max_size so no single export can grow unbounded.
• Enable compression: gzip on otlphttp exporters — it is nearly free and multiplies your effective size budget.
• Align proxy/gateway body limits (client_max_body_size, Envoy max_request_bytes) with your real compressed batch size, plus margin.
• Trim oversized span attributes and log bodies with the transform or attributes processor before they reach the exporter.
• Alert on otelcol_exporter_send_failed_spans so a size regression is caught before it becomes sustained data loss.
• Load-test with production-scale batches so the largest realistic request is validated against every cap on the path.

Quick Command Reference

# Watch the Collector for 413 rejections
journalctl -u otelcol-contrib -f | grep -i '413\|too large'

# Probe the backend/proxy body limit directly
curl -v -X POST https://otel.example.com/v1/traces \
  -H 'Content-Type: application/x-protobuf' --data-binary @traces.pb

# Confirm batch sizing in the running config
otelcol-contrib validate --config /etc/otelcol-contrib/config.yaml

# Check exporter failure metrics
curl -s http://localhost:8888/metrics | grep otelcol_exporter_send_failed

Conclusion

A 413 Request Entity Too Large on OTLP/HTTP is a size mismatch, not a transient fault: a batch exceeded a hard body limit on the backend or a proxy in front of it. Fix it from both ends — cap send_batch_max_size and turn on gzip compression so exports stay small, and raise the proxy or gateway body limit to match your real payloads. Because the rejection is deterministic, retries alone will not save the data; the batch must physically fit the cap.

Related

• OpenTelemetry Error Guide: ‘ResourceExhausted: received message larger than max’
• OpenTelemetry Error Guide: ‘sending queue is full’
• OpenTelemetry Error Guide: ‘partial success’ spans dropped