Troubleshooting Nginx 413 Request Entity Too Large Error: client_max_body_size Configuration

Resolve Nginx 413 'client intended to send too large body' errors by correctly configuring client_max_body_size in your Nginx setup.

The Nginx 413 Request Entity Too Large error is a common hurdle faced by web administrators, particularly when dealing with file uploads or large data submissions through web forms. This guide provides a comprehensive, technical walkthrough to diagnose and resolve this issue by correctly adjusting Nginx’s configuration parameters, ensuring your web applications can handle larger requests without interruption.

Symptom & Error Signature

When a client attempts to send a request body (e.g., a file upload, a large POST request) that exceeds the configured limit on the Nginx server, the server will reject the request and return a 413 Request Entity Too Large HTTP status code.

What you might see:

  • In your browser: A generic “413 Request Entity Too Large” page, sometimes branded by Nginx, or a custom error page if configured.
  • In Nginx access logs (/var/log/nginx/access.log): 
    192.168.1.1 - user [27/Jun/2026:10:30:00 +0000] "POST /upload HTTP/1.1" 413 199 "-" "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
  • In Nginx error logs (/var/log/nginx/error.log): 
    2026/06/27 10:30:00 [error] 12345#12345: *6789 client intended to send too large body: 12345678 bytes, client: 192.168.1.1, server: yourdomain.com, request: "POST /upload HTTP/1.1", host: "yourdomain.com"
    The client intended to send too large body message is the definitive indicator of this issue in the error logs.

Root Cause Analysis

The 413 Request Entity Too Large error originates from a security and resource management directive within Nginx called client_max_body_size. This directive sets the maximum allowed size of the client request body, specified in bytes, kilobytes (k/K), or megabytes (m/M).

Why is this limit in place? By default, Nginx sets a conservative limit (often 1MB) for client_max_body_size. This serves several critical purposes:

  1. Denial-of-Service (DoS) Prevention: Without a limit, malicious actors could send arbitrarily large requests, consuming server memory and CPU resources, potentially leading to a server crash or unresponsiveness.
  2. Resource Management: It helps manage server resources by preventing legitimate but excessively large uploads from consuming all available memory or disk I/O, impacting other services or users.
  3. Application-Specific Needs: It can enforce limits consistent with the application’s design, preventing uploads larger than the application is designed to handle or store.

Where client_max_body_size can be defined:

The client_max_body_size directive can be specified in the http, server, or location contexts within your Nginx configuration.

  • http context: Applies globally to all virtual hosts (servers).
  • server context: Applies to a specific virtual host.
  • location context: Applies to a specific URI path or location within a virtual host, overriding any server or http level settings.

Other Potential Bottlenecks (especially with PHP applications):

If you’re running a PHP application, Nginx isn’t the only component with body size limits. PHP itself has directives that control upload sizes, which can also cause similar issues if not properly aligned with Nginx:

  • upload_max_filesize: The maximum size of an uploaded file.
  • post_max_size: The maximum size of POST data that PHP will accept. This must be greater than or equal to upload_max_filesize.

If Nginx’s client_max_body_size is increased but PHP’s limits remain low, PHP will reject the request after Nginx has already accepted it, potentially leading to different errors or silent failures.

Step-by-Step Resolution

The solution involves increasing the client_max_body_size directive in your Nginx configuration, and potentially adjusting PHP-FPM settings if applicable.

1. Identify Your Nginx Configuration Files

Nginx configurations are typically located in /etc/nginx/.

  • The main configuration file is usually /etc/nginx/nginx.conf.
  • Site-specific configurations are often found in /etc/nginx/sites-available/ and symlinked to /etc/nginx/sites-enabled/.

Use the following command to see where your Nginx is loading its configuration from:

sudo nginx -t

This command will test your Nginx configuration and show the main config file path, usually indicating included directories.

2. Adjust Nginx client_max_body_size

You need to decide where to place the client_max_body_size directive based on its scope. For most cases, setting it within the server block of your specific website’s configuration is the most appropriate.

Example: Modifying a site-specific configuration

Let’s assume your website’s configuration is in /etc/nginx/sites-available/yourdomain.com.conf.

  1. Open the configuration file for editing:

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

  2. Locate the server block for your domain and add or modify the client_max_body_size directive. Choose a value that accommodates your needs (e.g., 20M for 20 Megabytes, 100M for 100 Megabytes).

    server {
    listen 80;
    listen [::]:80;
    server_name yourdomain.com www.yourdomain.com;
    root /var/www/yourdomain.com/html;
    index index.php index.html index.htm;

    # Add or modify this line:
    client_max_body_size 20M; # Example: Allows requests up to 20MB

    location / {
        try_files $uri $uri/ =404;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock; # Adjust PHP-FPM socket as needed
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    # ... other configurations
}

    [!IMPORTANT]

    • Choosing the right context:
      • If placed in the http block in /etc/nginx/nginx.conf, it affects all sites on the server.
      • If placed in a server block, it affects only that specific virtual host.
      • If placed in a location block, it affects only requests matching that location, overriding parent settings. Use location blocks if only a specific path (e.g., /upload) needs a higher limit.
    • Units: You can use k, m, g (case-insensitive) for kilobyte, megabyte, gigabyte. Without a unit, Nginx assumes bytes. 0 disables checking of client request body size.

3. (Optional) Adjust PHP-FPM Configuration

If your Nginx server is handling PHP applications, you must also ensure that PHP’s own upload limits are sufficient.

  1. Locate your php.ini file: The location typically varies by PHP version. You can find it by creating a phpinfo.php file with <?php phpinfo(); ?> and browsing to it, or by running:

    php -i | grep "Loaded Configuration File"

    Common paths include /etc/php/8.1/fpm/php.ini (for PHP 8.1 FPM).

  2. Edit php.ini:

    sudo nano /etc/php/8.1/fpm/php.ini # Adjust path for your PHP version

  3. Modify the following directives: Find and adjust upload_max_filesize and post_max_size. These values should be equal to or greater than the client_max_body_size you set in Nginx.

    upload_max_filesize = 15M # Example: Max file upload size
post_max_size = 20M       # Example: Max POST data size (must be >= upload_max_filesize)

    [!IMPORTANT]

    • post_max_size must be greater than or equal to upload_max_filesize. If post_max_size is smaller, uploads will fail.
    • Also consider memory_limit if you expect very large files or complex processing, as it can affect how PHP handles large uploads.

  4. Restart PHP-FPM: After modifying php.ini, you must restart the PHP-FPM service for changes to take effect:

    sudo systemctl restart php8.1-fpm # Adjust service name for your PHP version

4. Validate Nginx Configuration and Restart

After making changes to Nginx configuration files, it’s crucial to test the configuration for syntax errors and then reload or restart Nginx.

  1. Test Nginx configuration:

    sudo nginx -t

    You should see nginx: the configuration file /etc/nginx/nginx.conf syntax is ok and nginx: configuration file /etc/nginx/nginx.conf test is successful. If there are errors, review your changes carefully.

  2. Reload Nginx: If the test is successful, reload Nginx to apply the changes without dropping connections:

    sudo systemctl reload nginx

    [!WARNING]

    • Use sudo systemctl reload nginx to apply changes gracefully. This avoids dropping active connections.
    • Only use sudo systemctl restart nginx if reload fails or if directed by specific troubleshooting steps, as it will briefly interrupt service.

5. (For Dockerized Environments) Update Nginx Dockerfile/Config

If your Nginx setup is containerized using Docker, you’ll need to update your Docker image or volume mounts.

  1. Create a Custom Nginx Configuration File: Create a new file, for example, nginx-custom.conf, in your project directory:

    # nginx-custom.conf
http {
    client_max_body_size 20M; # Adjust as needed
    include /etc/nginx/conf.d/*.conf; # Include default site configs
    # ... other http configurations
}

    Or, if you only need to modify a specific server block, modify your existing site config file (e.g., default.conf or yourdomain.conf).

  2. Update Dockerfile (if building a custom image): Modify your Dockerfile to copy your custom Nginx configuration:

    # Dockerfile
FROM nginx:stable-alpine

COPY ./nginx-custom.conf /etc/nginx/nginx.conf # Overwrite main config
# OR, if modifying an existing site config:
# COPY ./yourdomain.conf /etc/nginx/conf.d/yourdomain.conf

# ... other Dockerfile instructions

  3. Update docker-compose.yml (if using Docker Compose): If you’re mounting configuration files, update your volumes section to include your modified config:

    # docker-compose.yml
version: '3.8'
services:
  nginx:
    image: nginx:latest
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx-custom.conf:/etc/nginx/nginx.conf:ro # Mount custom main config
      # OR, to mount a specific site config:
      # - ./nginx/conf.d/yourdomain.conf:/etc/nginx/conf.d/default.conf:ro
      - ./web:/var/www/html:ro # Your web root
    depends_on:
      - php
  php:
    image: php:8.1-fpm # Or your specific PHP image
    volumes:
      - ./web:/var/www/html:rw
      - ./php/php.ini:/usr/local/etc/php/php.ini:ro # Mount custom php.ini

  4. Rebuild and Restart Containers:

    docker-compose down
docker-compose build # If you changed the Dockerfile
docker-compose up -d

After performing these steps, your Nginx server (and PHP-FPM, if applicable) should now be configured to accept larger request bodies, resolving the 413 Request Entity Too Large error. Always test with a large file upload or POST request to confirm the fix.