Registry "413 Request Entity Too Large" on layer push in CI
A large image layer exceeded the maximum request body size of a proxy or gateway sitting in front of the registry, which answered 413. The registry itself may be fine; the cap is in the ingress/reverse proxy. Raise the body-size limit, or reduce the layer size.
What this error means
docker push fails with "received unexpected HTTP status: 413 Request Entity Too Large" on a big layer, often against a self-hosted registry behind nginx or a cloud load balancer.
failed to push: received unexpected HTTP status: 413 Request Entity Too LargeCommon causes
A reverse proxy caps the request body
nginx defaults to a 1m client_max_body_size; an image layer larger than the cap is rejected with 413 before reaching the registry.
A load balancer or gateway size limit
A managed ingress or API gateway in front of the registry enforces its own maximum payload size.
How to fix it
Raise the proxy body-size limit
Set the front proxy to allow unlimited (or large) request bodies so big layers pass through.
# nginx in front of the registry
client_max_body_size 0;Shrink oversized layers
Split or reduce large layers (multi-stage builds, smaller base, fewer COPY-everything steps) so no single layer trips the limit.
# combine and clean in one layer to keep it small
RUN apt-get update && apt-get install -y curl \
&& rm -rf /var/lib/apt/lists/*How to prevent it
- Configure the registry proxy to allow large request bodies.
- Keep layers small with multi-stage builds and cleanup.
- Test pushes of representative image sizes through the proxy.