Nginx 413 Request Entity Too Large: Resolving client_max_body_size on Ubuntu 20.04 LTS

Fix Nginx 413 Request Entity Too Large errors on Ubuntu 20.04 LTS by adjusting client_max_body_size. A comprehensive guide for SysAdmins.

As a seasoned SysAdmin and DevOps engineer, encountering the 413 Request Entity Too Large error from Nginx is a common sign that a user or application is attempting to upload data exceeding the web server's configured limits. This guide will walk you through diagnosing and resolving this specific Nginx error on an Ubuntu 20.04 LTS server, focusing on the client_max_body_size directive.

Symptom & Error Signature

When this error occurs, users attempting to upload files or submit forms with large data payloads will typically encounter a generic Nginx error page in their browser displaying "413 Request Entity Too Large". The operation will fail, and the data will not be processed by the backend application.

In your Nginx error logs, usually located at /var/log/nginx/error.log, you will see entries similar to these:

2023/10/26 14:35:01 [error] 12345#12345: *123 client intended to send too large body: 12345678 bytes, client: 192.168.1.100, server: yourdomain.com, request: "POST /upload HTTP/1.1", host: "yourdomain.com"

The key phrase here is client intended to send too large body. The number 12345678 represents the size of the request body in bytes that Nginx rejected.

Root Cause Analysis

Nginx, by default, imposes a limit on the size of the client request body. This is a crucial security and resource management feature designed to prevent malicious attacks (like DoS attempts by sending excessively large requests) and to ensure that a single client doesn't consume all available server resources.

The client_max_body_size directive in Nginx controls this limit. Its default value is typically 1m (1 megabyte). When an incoming HTTP request contains a body (e.g., file uploads, POST data) that exceeds the value specified by client_max_body_size, Nginx will immediately terminate the connection, log the error, and return an HTTP 413 Request Entity Too Large status code to the client.

This directive can be configured in different contexts within the Nginx configuration:

• http context: Applies globally to all virtual hosts on the server.
• server context: Applies to a specific virtual host (domain).
• location context: Applies to a specific URI path within a virtual host.

The most specific directive takes precedence. For example, a client_max_body_size set within a location block will override one set in the server block for requests matching that location.

Step-by-Step Resolution

To resolve the 413 Request Entity Too Large error, you need to increase the client_max_body_size directive in your Nginx configuration.

1. Locate Your Nginx Configuration Files

Nginx configurations on Ubuntu 20.04 are typically structured as follows:

• /etc/nginx/nginx.conf: The main Nginx configuration file.
• /etc/nginx/conf.d/*.conf: Directory for additional global configurations.
• /etc/nginx/sites-available/: Contains configuration files for individual websites (virtual hosts).
• /etc/nginx/sites-enabled/: Contains symbolic links to files in sites-available for active websites.

You'll usually want to modify the configuration for the specific website (server block) or even a specific path (location block) that is experiencing the upload issue.

To find which configuration file is active for your domain, you can inspect the sites-enabled directory:

ls -l /etc/nginx/sites-enabled/

This will show you the symbolic links pointing to the actual configuration files in sites-available. For example, if your domain is yourdomain.com, you might find /etc/nginx/sites-enabled/yourdomain.com.conf pointing to /etc/nginx/sites-available/yourdomain.com.conf.

2. Modify the client_max_body_size Directive

Open the relevant Nginx configuration file using your preferred text editor. For this example, let's assume we are editing /etc/nginx/sites-available/yourdomain.com.conf.

sudo nano /etc/nginx/sites-available/yourdomain.com.conf

Inside this file, you can place the client_max_body_size directive within the http, server, or location block, depending on the scope you need.

• Option A: Global (http context) Edit /etc/nginx/nginx.conf. This affects all sites served by this Nginx instance.

  # /etc/nginx/nginx.conf
  http {
      # ... other http directives ...
      client_max_body_size 100M; # Set to 100 megabytes
      # ...
  }
  

• Option B: Per-Site (server context) Edit your site's configuration file (e.g., /etc/nginx/sites-available/yourdomain.com.conf). This is generally the most common and recommended approach.

  # /etc/nginx/sites-available/yourdomain.com.conf
  server {
      listen 80;
      server_name yourdomain.com www.yourdomain.com;
  
      client_max_body_size 50M; # Set to 50 megabytes for this specific domain
  
      # ... other server directives ...
  
      location / {
          # ...
      }
  }
  

• Option C: Specific Path (location context) If only a particular upload path needs a higher limit, you can set it within a location block. This directive within a location block will override any client_max_body_size set in its parent server or http blocks for requests to that specific URI.

  # /etc/nginx/sites-available/yourdomain.com.conf
  server {
      listen 80;
      server_name yourdomain.com www.yourdomain.com;
  
      client_max_body_size 10M; # Default for the server
  
      location / {
          # ...
      }
  
      location /uploads {
          client_max_body_size 200M; # Allow larger uploads only to /uploads
          # ...
      }
  }
  

Choose a value appropriate for your needs. Common values include 10M, 50M, 100M, or even 500M. The M suffix indicates megabytes. You can also use G for gigabytes or K for kilobytes.

While it might be tempting to set a very high value (e.g., 1G), consider the security and resource implications. An excessively large client_max_body_size could make your server vulnerable to resource exhaustion attacks or allow users to upload unnecessarily large files, impacting disk space and bandwidth. Set the limit to the minimum required value.

3. Validate Nginx Configuration Syntax

After modifying the configuration file, it's crucial to test its syntax before reloading Nginx. This prevents service outages due to typos or incorrect directives.

sudo nginx -t

A successful output will look like this:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

If there are errors, Nginx will display detailed messages indicating the file and line number where the issue is located. Correct any errors before proceeding.

4. Reload Nginx Service

Once the configuration syntax is verified, reload Nginx to apply the changes. A reload is preferred over a restart as it allows Nginx to gracefully shut down old worker processes and start new ones with the updated configuration, without dropping active connections.

sudo systemctl reload nginx

Always use sudo systemctl reload nginx for applying Nginx configuration changes in a production environment. A restart could briefly interrupt service for active users, while a reload ensures zero downtime for existing connections.

5. Consider PHP-FPM Limits (If Applicable)

If your Nginx server is acting as a reverse proxy for a PHP application (e.g., WordPress, Laravel, Symfony) via PHP-FPM, you might also need to adjust PHP's own upload limits. Nginx handles the initial request, but if PHP's limits (upload_max_filesize and post_max_size) are lower than Nginx's client_max_body_size, PHP might still reject the upload even after Nginx accepts it.

You'll typically find PHP configuration in /etc/php/<php_version>/fpm/php.ini. For Ubuntu 20.04, this is commonly php7.4.

sudo nano /etc/php/7.4/fpm/php.ini

Locate and adjust the following directives:

; Maximum allowed size for uploaded files.
upload_max_filesize = 50M

; Maximum size of POST data that PHP will accept.
post_max_size = 50M

post_max_size should always be equal to or greater than upload_max_filesize. Both values should generally be at least as high as your client_max_body_size in Nginx, if not higher, to accommodate other POST data overhead.

After modifying php.ini, you must reload the PHP-FPM service:

sudo systemctl reload php7.4-fpm

Adjust the version number (php7.4-fpm) if you are running a different PHP version.

6. Test the Upload

Finally, attempt the large file upload or form submission again to verify that the 413 Request Entity Too Large error is resolved and your application can now handle the larger data payloads. Monitor your Nginx error logs (/var/log/nginx/error.log) and PHP-FPM logs (if applicable, e.g., /var/log/php7.4-fpm.log) for any new errors during the test.