Australian cloud for business software — built and run in Sydney since 2002

NetLeverage
NetLeverage

nginx 413 Request Entity Too Large: client_max_body_size and the limits behind it

Technical article
Troubleshooting

About this article: This article is reviewed against the cited sources. This is source research, not lab validation. Check the stated versions and your own requirements before making changes.

An upload that works for small files and fails for larger ones with "413 Request Entity Too Large" has hit an nginx size limit, and the default is small: client_max_body_size is 1m. nginx compares it with the size the client announces, and when the request is larger it returns 413 before reading the body and writes client intended to send too large body to the error log with the number of bytes it saw. Raise the limit for the location that takes uploads, then check the limits behind nginx (PHP, Apache, the application), because each layer has its own and the upload fails at the smallest.

What the error means

The nginx documentation for client_max_body_size says: "Sets the maximum allowed size of the client request body. If the size in a request exceeds the configured value, the 413 (Request Entity Too Large) error is returned to the client." The default is 1m, the directive is allowed in the http, server and location contexts, and "setting size to 0 disables checking of client request body size". The documentation adds a warning: "Please be aware that browsers cannot correctly display this error", so a user may see a failed upload rather than the nginx error page. The error log is the reliable record.

In the nginx 1.30.6 source, the check runs when the request headers are processed. If the Content-Length header is larger than the limit, nginx logs client intended to send too large body: %O bytes (at the error level, with the number of bytes), discards the body and finishes the request with 413. For a chunked upload, where there is no Content-Length, nginx checks as the chunks arrive and logs client intended to send too large chunked body with the sum so far and the next chunk size.

The size suffixes follow nginx's syntax page: k and K for kilobytes, m and M for megabytes. In the source, m is 1024 x 1024 = 1,048,576 bytes.

Likely causes

Cause What you see How to confirm
Upload larger than the default 1m 413 for files above about 1 MiB. Smaller files work client intended to send too large body: N bytes in the nginx error log
Limit set at one level, upload handled at another Raising the limit in server has no effect on one URL nginx -T: a location block with its own client_max_body_size
Chunked upload The log line says chunked body The same error log, with two numbers joined by +
A second layer refuses the upload 413 appears but nginx logs no too large body line Another proxy, Apache, or the application generated it. Check the response body and Server header
PHP limits lower than the nginx limit The upload completes at nginx but the application reports no file upload_max_filesize default 2M, post_max_size default 8M
Many files in one request An upload of more than 20 files at once misbehaves while single-file uploads work max_file_uploads, default 20, documented as "The maximum number of files allowed to be uploaded simultaneously"

Prove the cause before changing anything

1. Look for the nginx log line.

Search the error log (find its path with nginx -T, which dumps the configuration) for too large. If the line is present, nginx produced the 413 and the byte count is the size nginx saw. If there is no such line, another layer produced it. That points away from nginx, to the layers below.

2. Read the configuration.

nginx -T

Search the output for client_max_body_size. Note every occurrence and which server and location it belongs to, then match the failing URL to its location block.

3. Reproduce with a file of a known size.

curl -s -i --data-binary @sample.bin https://app.example.com/upload

--data-binary @file posts the file exactly as it is, and -i shows response headers. A 413 with an nginx Server header and the too large body line confirms the cause. Use a file just under and just over the limit to find the boundary. Browsers upload with multipart form encoding, which adds some overhead to the file size, so the number nginx logs is slightly larger than the file.

4. Check the layers behind nginx. For PHP, read upload_max_filesize, post_max_size and memory_limit in the PHP configuration. For Apache behind nginx, read LimitRequestBody. Neither is changed by editing nginx.

Fix

Disruptive step: every change below alters what the live server accepts. Keep a copy of each file before editing it, test the syntax, and restore the copy if uploads or other traffic misbehave.

Raise the nginx limit where uploads are handled

location /upload {
    client_max_body_size 20m;
}

Use the smallest value that meets the real requirement, and apply it to the upload location, not to the whole server. A server-wide or http-wide large limit lets any URL accept big bodies.

Disruptive step: the change takes effect after nginx -t and nginx -s reload, which "start the new worker process with a new configuration, gracefully shut down old worker processes". To back out, restore the previous file and reload.

Match the PHP limits

The PHP manual says of post_max_size: "This setting also affects file upload. To upload large files, this value must be larger than upload_max_filesize." If post data is greater than post_max_size, "the $_POST and $_FILES superglobals are empty". Defaults are upload_max_filesize 2M, post_max_size 8M and max_file_uploads 20. The manual also lists other limits that can bite: memory_limit, max_execution_time and max_input_time, which includes "file uploads" and can be exceeded by "large or multiple files, or users on slower connections".

Disruptive step: changing PHP settings needs a reload of PHP-FPM or the web server. To back out, restore the previous file. As with nginx, raise the PHP limits only as far as the upload page needs, because a higher limit applies to every script that uses the same configuration.

Apache behind nginx

LimitRequestBody restricts the request body. The Apache 2.4 documentation gives a default of 1073741824 bytes (1 GiB), and says that in 2.4.53 and earlier the default "was 0 (unlimited)". A value of 0 means unlimited.

Risk: raising LimitRequestBody lets the Apache behind nginx accept larger bodies, and 0 removes the limit. Change it only if Apache's own limit is what refused the upload. To back out, restore the previous value and reload Apache.

Buffering and disk

With proxy_request_buffering on (the default), "the entire request body is read from the client before sending the request to a proxied server". A large upload therefore spends time and temporary disk space in nginx. client_body_buffer_size ("8k|16k") sets how much stays in memory before a temporary file is used.

Example (illustrative): a customer uploads a 3 MiB photo to app.example.com/upload and gets 413. The error log shows client intended to send too large body: 3146000 bytes. The default limit is 1m = 1,048,576 bytes, and 3,146,000 ÷ 1,048,576 = 3.0 MiB, so the default is far too small. The administrator sets client_max_body_size 8m; for location /upload (8 x 1,048,576 = 8,388,608 bytes). The upload now reaches PHP, which has post_max_size of 8M and upload_max_filesize of 2M, and the 3 MiB file is refused there instead. Setting upload_max_filesize to 6M and leaving post_max_size at 8M lets it through, with post_max_size larger than upload_max_filesize as the manual requires.

Confirm the fix

  1. Repeat the curl test with a file just under the new limit: the request reaches the application and returns its normal response.
  2. Repeat with a file just over: it still fails with 413 and a too large body line. The limit should still exist.
  3. Upload through a real browser, not only curl, because multipart overhead and client behaviour differ.
  4. Check that unrelated URLs keep the old, lower limit.

What to watch afterwards

  • Keep a record of each location with a raised limit, with the reason and the largest legitimate file.
  • Watch the error log for too large body lines. A burst from one address can be an abuse attempt rather than a limit problem.
  • Watch free disk space where nginx writes temporary request bodies.
  • When the application moves to a new PHP or web server version, recheck all three limits together.

Risks and limits

  • These commands have not been run or lab-tested. They are taken from the nginx, PHP, Apache and curl documentation and the nginx source listed below.
  • A larger limit lets clients send larger bodies to the whole location. Combine it with authentication and, where relevant, rate limits.
  • Browsers and cloud load balancers or CDNs in front of nginx have their own limits, not covered here.
  • Very large files are better sent in parts that can resume. "Large Uploads Stall or Restart: Multipart, Resume and Leftover Parts" covers that approach.
  • The log lines are from nginx 1.30.6. Other versions may word them differently.

Sources