Also at Deasil Works · txn2 · Plexara
Profiles GitHub · X · LinkedIn
Theme Light · Auto · Dark
imti.co
Professional notes by Craig Johnston
long-form, short-form, working drafts · since 2008
VOL. XIX · MMXXVI
115 NOTES IN PRINT
FOLIO VII 2018-03-31 · 4 MIN · SHORT-FORM

Kubernetes - 413 Request Entity Too Large

Configuring the NGINX Ingress Controller

Diagram · folio vii
sequenceDiagram
    autonumber
    actor C as Client
    participant ING as Ingress-nginx
    participant API as API service

    Note over C: client uploads 50MB JSON
    C->>ING: POST /api/data (50MB)
    Note over ING: default proxy-body-size 1m
    ING-->>C: 413 Request Entity Too Large

    Note over ING: ops adds annotation -<br/>proxy-body-size 100m

    C->>ING: POST /api/data (50MB) again
    ING->>API: forward (within new limit)
    API-->>ING: 200
    ING-->>C: 200 OK

When setting up nginx ingress on Kubernetes for a private Docker Registry, I ran into an error when trying to push an image to it.

Error parsing HTTP response: invalid character '<' looking for beginning of value: "<html>\r\n<head><title>413 Request Entity Too Large</title></head>\r\n<body bgcolor=\"white\">\r\n<center><h1>413 Request Entity Too Large</h1></center>\r\n<hr><center>nginx/1.9.14</center>\r\n</body>\r\n</html>\r\n"

The “413 Request Entity Too Large” error is something many accustomed to running nginx as a standard web server/proxy. nginx is configured to restrict the size of files it will allow over a post. This restriction helps avoid some DoS attacks. The default values are easy to adjust in the Nginx configuration. However, in the Kubernetes world things are a bit different. I prefer to do things the Kubernetes way; however, there is still a lack of established configuration idioms, since part of its appeal is flexibility. One thousand different ways of doing something means ten thousand variations of remedies to every potential problem. Googling errors in the Kubernetes world leads to a mess of solutions not always explicitly tied to an implementation. I am hoping that as Kubernetes continues to gain popularity more care will be taken to provide context for solutions to common problems.

§2026 Update

Big news first: the controller this post configures, the community ingress-nginx project, has been retired. The Kubernetes project announced the retirement in November 2025, and best-effort maintenance ended in March 2026. No further releases, bug fixes, or security patches are coming. Part of what pushed this was IngressNightmare, a set of vulnerabilities disclosed in March 2025 whose worst, CVE-2025-1974, was a 9.8-severity unauthenticated remote code execution against the admission webhook. If you are still running ingress-nginx in 2026, treat migration as urgent rather than optional.

Where to go from here: SIG Network recommends moving to the Gateway API, the modern successor to Ingress, or to another maintained controller. Worth knowing, the separate, F5-maintained NGINX Ingress Controller (the nginxinc/kubernetes-ingress project, confusingly similar in name) is a different product and is still supported.

The lesson in this post outlives the controller, though. A 413 from any nginx in front of your service is a body-size limit, and you fix it wherever that proxy reads its config:

  • On an existing ingress-nginx install, the annotation below still works: nginx.ingress.kubernetes.io/proxy-body-size.
  • On the F5 NGINX Ingress Controller, the equivalent is nginx.org/client-max-body-size.
  • Under the Gateway API there is no single core body-size field. The limit is set by your chosen implementation (Envoy Gateway, NGINX Gateway Fabric, and others each expose it differently), so check your controller’s docs.

The original write-up, which still applies to any ingress-nginx you have not yet migrated, follows.

Original article below. Everything from here down is the post as originally written. The 2026 Update above covers what’s changed since.

§Context

I now use the official NGINX Ingress Controller, there are quite a few options out there, so this solution only applies to the official NGINX Ingress Controller. If you don’t already have it, you can follow the easy ingress controller deployment instructions.

I found this solution in the Ingress examples folder in the Github repository. I probably should have started there on my journey to set up a private Docker registry on my Kubernetes cluster.

Using annotations you can customize various configuration settings. In the case of nginx upload limits, use the annotation below:

nginx.ingress.kubernetes.io/proxy-body-size: "0"

The annotation (see its context in the gist: Registry Ingress Example above) removes any restriction on upload size. Of course, you can set this to a size appropriate to your situation.

§Still Not Working?

Maybe you installed the NGINX Ingress Controller wrong as I did. I was rushing to get a project done at 3 am, cutting and pasting commands like a wild monkey. I installed the non-RBAC based configuration; however, my cluster uses RBAC. To make things worse, everything else was working fine for some reason (at least it seemed to) until this configuration issue came up and the annotations were not working. Double check your install steps.

§Not the Ingress Controller you are using?

Here are some solutions for alternative implementations:

· 2018-03-31 ← back to all notes