Docker Push "413 Request Entity Too Large" - Fix Oversized Layers/Proxy Limits

The registry (or a reverse proxy in front of it) rejected a blob upload with 413 because the layer exceeds its maximum allowed body size. The build is fine; a single layer is simply too big for the upload limit.

What this error means

A docker push fails on a specific large layer with received unexpected HTTP status: 413 Request Entity Too Large. Smaller layers push fine; only the oversized blob is rejected.

docker push output

received unexpected HTTP status: 413 Request Entity Too Large
# uploading a large blob through a proxy with a body-size cap

Common causes

A reverse proxy caps the upload body size

An nginx/ingress in front of the registry with a low client_max_body_size rejects large blob PUTs with 413 before they reach the registry.

A single layer is genuinely huge

Bundling large artifacts (datasets, model weights, vendored binaries) into one layer can exceed registry or proxy limits.

Chunked upload disabled or limited

If monolithic uploads are forced and the limit is low, even a moderately large layer fails on commit.

How to fix it

Reduce layer size

Split the oversized content across smaller layers and strip what is not needed.

Dockerfile

# break a huge COPY/RUN into smaller steps and remove intermediates
RUN curl -o /tmp/big.tar ... && tar xf /tmp/big.tar -C /opt && rm /tmp/big.tar

Raise the proxy body-size limit (self-hosted)

For a registry behind nginx, increase the allowed body size.

nginx.conf

# nginx in front of the registry
client_max_body_size 0;   # or a large explicit value, e.g. 2g

How to prevent it

Keep individual layers well under the registry/proxy upload limit.
Avoid baking very large artifacts into a single layer.
For self-hosted registries, set a generous client_max_body_size.