Troubleshooting Nginx 413 Request Entity Too Large Error: Resolving Upload Limit Issues

Resolve Nginx 413 'Request Entity Too Large' errors by configuring client_max_body_size. This guide helps you fix upload limits for large files on your web server.

When managing web applications that require users to upload files, encountering an “Nginx 413 Request Entity Too Large” error can be a frustrating roadblock. This error indicates that Nginx, acting as your web server or reverse proxy, has rejected an incoming request because its body size (typically a file upload) exceeds a predefined limit. This guide provides a comprehensive, step-by-step resolution for this common issue, ensuring your web applications can handle larger file uploads successfully.

Symptom & Error Signature

Users attempting to upload files to your web application (e.g., images, videos, documents via a CMS, API, or custom form) will be met with an error message in their browser, typically a generic Nginx 413 page or a custom application error indicating the upload failed due to size.

Browser Output:

413 Request Entity Too Large
nginx/1.24.0

Nginx Error Log Output (/var/log/nginx/error.log):

2026/06/27 10:30:15 [error] 12345#12345: *6789 client intended to send too large body: 52428800 bytes, client: 192.168.1.10, server: example.com, request: "POST /upload HTTP/1.1", host: "example.com"

The client intended to send too large body message is the definitive indicator within the Nginx logs, often showing the exact byte size of the attempted upload that exceeded the limit.

Root Cause Analysis

The “Nginx 413 Request Entity Too Large” error is primarily caused by the client_max_body_size directive in your Nginx configuration. This directive sets the maximum allowed size of the client request body, specified in bytes, kilobytes (K), or megabytes (M). By default, Nginx sets this limit to a conservative 1MB.

When an HTTP request contains a body larger than the value specified by client_max_body_size, Nginx will terminate the connection, log the error, and return a 413 (Request Entity Too Large) HTTP status code to the client. This mechanism is a security measure to prevent denial-of-service (DoS) attacks where an attacker might attempt to exhaust server resources by sending excessively large requests.

While Nginx is often the first line of defense, it’s important to note that upstream application servers (like PHP-FPM, Node.js, Python Gunicorn, etc.) also have their own request body size limits. If Nginx successfully forwards a large request, the upstream server might still reject it if its own limits are exceeded. This guide focuses on resolving the Nginx-specific limit first.

Step-by-Step Resolution

To resolve the Nginx 413 error, you need to increase the client_max_body_size directive in your Nginx configuration to a value that accommodates your desired upload sizes.

1. Accessing Nginx Configuration Files

Nginx configurations are typically organized in a modular fashion. You’ll need to locate the relevant configuration file(s) for your server setup. Common locations include:

  • Main Nginx configuration: /etc/nginx/nginx.conf
  • Site-specific virtual host configurations: /etc/nginx/sites-available/your_domain.conf (linked to /etc/nginx/sites-enabled/)
  • Included configuration snippets: /etc/nginx/conf.d/*.conf

[!TIP] On a typical Ubuntu/Debian server, site-specific configurations are often found in /etc/nginx/sites-available/ and enabled via a symbolic link in /etc/nginx/sites-enabled/. Identify the configuration file for the domain exhibiting the error.

Use a text editor like nano or vi to open the configuration file. For example:

sudo nano /etc/nginx/nginx.conf

Or, for a site-specific configuration:

sudo nano /etc/nginx/sites-available/your_domain.conf

2. Modifying client_max_body_size

The client_max_body_size directive can be placed in different contexts within the Nginx configuration:

  • http block (Global): Applies to all virtual hosts on the server. Useful if all your sites require the same large upload limit.
  • server block (Per Virtual Host): Applies only to a specific domain or virtual host. Recommended for granular control.
  • location block (Per Path/URL): Applies only to requests matching a specific URL path. Most specific control, useful for particular upload endpoints.

Example: Setting a global limit (in nginx.conf)

Add or modify the client_max_body_size directive within the http { ... } block:

# /etc/nginx/nginx.conf

http {
    # ... other http directives ...

    client_max_body_size 100M; # Set global maximum upload size to 100MB

    # ... more http directives ...
}

Example: Setting a per-server limit (in sites-available/your_domain.conf)

Add or modify the directive within the server { ... } block for your specific domain:

# /etc/nginx/sites-available/your_domain.conf

server {
    listen 80;
    server_name your_domain.com www.your_domain.com;

    client_max_body_size 50M; # Set maximum upload size for this domain to 50MB

    # ... other server directives ...

    location / {
        # ...
    }
}

Example: Setting a per-location limit (for a specific upload endpoint)

This is useful if only certain parts of your application handle large uploads, and you want to keep general limits lower.

# /etc/nginx/sites-available/your_domain.conf

server {
    listen 80;
    server_name your_domain.com;

    client_max_body_size 10M; # Default for the server (e.g., 10MB)

    location /upload/large-files/ {
        client_max_body_size 200M; # Allow 200MB uploads only to this specific path
        proxy_pass http://backend_app;
        # ... other location directives ...
    }

    location / {
        # ... regular application serving ...
    }
}

[!IMPORTANT] Choose a value for client_max_body_size that is appropriate for your application’s needs. Setting an excessively large limit (e.g., several GBs) without proper resource management can still expose your server to potential resource exhaustion or DoS attacks. Always consider the maximum practical file size your users will upload.

3. Testing Nginx Configuration Syntax

After making changes to any Nginx configuration file, it’s crucial to test the syntax before reloading or restarting the service. This prevents Nginx from failing to start due to a misconfiguration.

sudo nginx -t

You should see output similar to this:

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

If you see any errors, carefully review your changes and correct them before proceeding.

4. Reloading or Restarting Nginx

Once the configuration syntax is verified, you need to apply the changes by reloading or restarting the Nginx service.

  • Reload (Recommended): reload applies changes gracefully without dropping active connections. 
    sudo systemctl reload nginx
  • Restart: restart terminates all current Nginx processes and starts new ones. Use if reload doesn’t seem to apply changes or if you made very fundamental changes. 
    sudo systemctl restart nginx

Verify the service status after reload/restart:

sudo systemctl status nginx

Ensure it shows active (running).

5. Addressing Upstream Server Limits (e.g., PHP-FPM)

If your Nginx server acts as a reverse proxy to an application server (e.g., PHP-FPM for WordPress/Laravel, Gunicorn for Django/Flask), you might also need to adjust its upload limits. Even if Nginx allows the large request body, the application server might reject it.

For PHP applications, the relevant directives are in php.ini:

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

Steps for PHP-FPM:

  1. Locate php.ini: The path varies by PHP version. Common paths include /etc/php/X.x/fpm/php.ini (where X.x is your PHP version, e.g., 8.2). 
    # Example for PHP 8.2
sudo nano /etc/php/8.2/fpm/php.ini
  2. Modify directives: Find and update upload_max_filesize and post_max_size. Ensure these values are at least as large as, or preferably slightly larger than, your client_max_body_size in Nginx. 
    ; Maximum allowed size for uploaded files.
upload_max_filesize = 50M

; Maximum size of POST data that PHP will accept.
post_max_size = 50M
  3. Restart PHP-FPM: After modifying php.ini, you must restart the PHP-FPM service for the changes to take effect. 
    sudo systemctl restart php8.2-fpm # Adjust for your PHP version

[!NOTE] For other upstream application servers (e.g., Node.js with Express, Python with Flask/Django, Java with Tomcat/Jetty), consult their respective documentation for configuring request body size limits.

6. Dockerized Nginx Environments

If your Nginx instance is running within a Docker container, the approach to modify its configuration differs slightly. You typically won’t edit /etc/nginx/nginx.conf directly inside a running container.

Common Docker Nginx Setup:

  1. Create a custom Nginx configuration file: Create a new file (e.g., nginx-custom.conf) on your host machine or within your project directory. This file will contain your client_max_body_size directive, either globally or for a specific server/location block.

    # nginx-custom.conf
# This file might be mounted into /etc/nginx/conf.d/ or similar

http {
    client_max_body_size 75M; # Set upload limit for Dockerized Nginx
    # Other http configurations if needed
}

# Or, if you're overriding a specific site config:
# server {
#     client_max_body_size 75M;
#     # ...
# }

  2. Mount the custom configuration into the container:

    • Using docker run: 
      docker run -p 80:80 \
           -v /path/to/your/nginx-custom.conf:/etc/nginx/conf.d/custom-limit.conf:ro \
           nginx:latest
    • Using docker-compose.yml (recommended for multi-service apps): 
      version: '3.8'
services:
  nginx:
    image: nginx:latest
    ports:
      - "80:80"
    volumes:
      - ./nginx-custom.conf:/etc/nginx/conf.d/custom-limit.conf:ro # Mount your custom config
      - ./my-website.conf:/etc/nginx/conf.d/default.conf:ro # Or override the default site config
    restart: always
  # ... other services like php-fpm, app server ...

  3. Rebuild/Restart Docker services: After modifying your Docker Compose file or docker run command, you’ll need to restart your Nginx container(s) to apply the new configuration.

    docker-compose down
docker-compose up -d

[!WARNING] Remember that if your Dockerized Nginx is configured to include /etc/nginx/conf.d/*.conf, mounting a file there is usually the most straightforward method. If you’re completely replacing /etc/nginx/nginx.conf or a site-specific config, ensure your custom file includes all necessary directives (like include /etc/nginx/conf.d/*.conf; if required) so you don’t break existing configurations.

After following these steps, your Nginx server should now correctly handle larger file uploads, resolving the “413 Request Entity Too Large” error. Always test with a file just over your previous limit and then well within your new limit to confirm the fix.