Limit File Upload Size in NGINX

By limiting the file size of uploads, you can prevent some types of Denial-of-Service (DoS) attacks and many other issues. By default, NGINX has an upload limit of 1 MB per file. By editing client_max_body_size, you adjust the file upload size.

Understanding client_max_body_size

The client_max_body_size directive sets the maximum allowed size of the client request body. If the size in a request exceeds the configured value, NGINX returns a 413 (Request Entity Too Large) error to the client.

ℹ️

Default Value

The default value is 1m (1 megabyte). Setting size to 0 disables checking of client request body size.

⚠️

Browser Display

Please be aware that browsers cannot correctly display the 413 error.

Directive Syntax

Syntax:  client_max_body_size size;
Default: client_max_body_size 1m;
Context: http, server, location

Valid Size Units

Configuration Contexts

Use the http, server, or location block to edit client_max_body_size:

• Changes to the http block affect all server blocks (virtual hosts)
• Changes to the server block affect a particular site or application
• Changes to the location block affect a particular directory for uploads under a site or application

Configuration Examples

Global Configuration (All Sites)

Edit /etc/nginx/nginx.conf:

http {
    client_max_body_size 100m;
    
    # Other http configuration...
}

Per-Site Configuration

Edit your site configuration file (e.g., /etc/nginx/sites-available/example.com):

server {
    listen 80;
    server_name example.com;
    
    client_max_body_size 50m;
    
    location / {
        # Site configuration...
    }
}

Per-Location Configuration

For specific upload endpoints:

server {
    listen 80;
    server_name example.com;
    
    # Default limit for the site
    client_max_body_size 10m;
    
    # Higher limit for upload endpoint
    location /uploads {
        client_max_body_size 500m;
    }
    
    # Lower limit for API endpoint
    location /api {
        client_max_body_size 5m;
    }
}

Disable Size Checking

location /unlimited-uploads {
    client_max_body_size 0;
}

❗️

Security Warning

Setting client_max_body_size 0; disables checking entirely. This is not recommended for production environments as it exposes the server to resource exhaustion attacks.

Applying Configuration Changes

Step 1: Test the Configuration

Before reloading NGINX, always test the configuration for syntax errors:

$ sudo nginx -t

Expected output:

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

Step 2: Reload NGINX

If the test is successful, reload NGINX to apply changes:

$ sudo nginx -s reload

Alternative method using systemd:

$ sudo systemctl reload nginx

ℹ️

Note

nginx -s reload reloads the configuration without restarting NGINX, maintaining active connections.

Related Directives

When working with large file uploads, you may also need to adjust these related directives:

client_body_timeout

Defines a timeout for reading client request body. The timeout is set only between two successive read operations, not for the transmission of the whole request body.

Syntax:  client_body_timeout time;
Default: client_body_timeout 60s;
Context: http, server, location

Example:

client_body_timeout 300s;  # 5 minutes

client_body_buffer_size

Sets buffer size for reading client request body. If the request body is larger than the buffer, the whole body or only its part is written to a temporary file.

Syntax:  client_body_buffer_size size;
Default: client_body_buffer_size 8k|16k;
Context: http, server, location

Example:

client_body_buffer_size 128k;

client_body_temp_path

Defines a directory for storing temporary files holding client request bodies.

Syntax:  client_body_temp_path path [level1 [level2 [level3]]];
Default: client_body_temp_path client_body_temp;
Context: http, server, location

Example:

client_body_temp_path /var/nginx/client_body_temp 1 2;

This creates a path like: /var/nginx/client_body_temp/7/45/00000123457

Complete Configuration Example

Here's a comprehensive example for a site with file upload functionality:

http {
    # Global settings
    client_max_body_size 20m;
    client_body_buffer_size 128k;
    client_body_timeout 300s;
    client_body_temp_path /var/nginx/client_body_temp 1 2;
    
    server {
        listen 80;
        server_name example.com;
        root /var/www/html;
        
        # Standard pages - 10MB limit
        location / {
            client_max_body_size 10m;
        }
        
        # File upload endpoint - 500MB limit
        location /upload {
            client_max_body_size 500m;
            client_body_timeout 600s;
        }
        
        # API endpoint - 5MB limit
        location /api {
            client_max_body_size 5m;
        }
    }
}

Verification

Check Active Configuration

To see the active client_max_body_size values across your configuration:

$ sudo nginx -T | grep client_max_body_size

Monitor Error Logs

If uploads are failing, check the error log:

$ sudo tail -f /var/log/nginx/error.log

Look for errors like:

client intended to send too large body: 104857600 bytes

Troubleshooting

Problem: Still Getting 413 Errors

Possible Causes:

1. Configuration not reloaded - Verify NGINX reloaded successfully

   Bash

   $ sudo systemctl status nginx

2. Directive in wrong context - Ensure the directive is in the correct http, server, or location block

3. Multiple configuration files - Check for conflicting directives in included files:

   Bash

   $ grep -r "client_max_body_size" /etc/nginx/

4. Backend application limits - The backend application (PHP, Node.js, etc.) may have its own upload limits that also need adjustment

Problem: Uploads Timing Out

If uploads start but never complete, increase timeout values:

client_body_timeout 600s;
send_timeout 600s;

Problem: Disk Space Issues

Large uploads require temporary disk space. Check available space:

$ df -h /var/nginx/client_body_temp

Backend Integration Requirements

⚠️

Important

Adjusting client_max_body_size in NGINX is not sufficient alone. Your backend application must also be configured to accept the same upload size.

PHP Configuration

Edit php.ini:

upload_max_filesize = 100M
post_max_size = 110M
memory_limit = 256M
max_execution_time = 300

Restart PHP-FPM:

sudo systemctl restart php-fpm

Reference Documentation

For complete details on the client_max_body_size directive and related configuration options, refer to the official NGINX documentation:

• Module ngx_http_core_module