Client_max_body_size Not Working in Nginx

Published July 01, 2024

Problem: Nginx's client_max_body_size directive not taking effect

When setting up Nginx, you might face an issue where the client_max_body_size directive doesn't work as expected. This can cause request rejections or file upload limits. Knowing why this happens and how to fix it is key for a well-working web server.

Configuring client_max_body_size in Nginx

Locating the Configuration File

The Nginx configuration file is usually in one of these locations:

  • /etc/nginx/nginx.conf
  • /usr/local/nginx/conf/nginx.conf
  • /usr/local/etc/nginx/nginx.conf

Server block configurations are often in separate files in the /etc/nginx/sites-available/ directory, with links in /etc/nginx/sites-enabled/.

Location block settings are in server blocks, allowing for specific configurations.

Setting the Upload Size Limit

The syntax for the client_max_body_size directive is:

client_max_body_size size;

Some values for different uses:

  • Small file uploads (profile pictures): 2-5 MB
  • Document uploads: 10-20 MB
  • Large file uploads (videos): 100 MB - 1 GB

To balance security and function:

  1. Set a default limit in the http block
  2. Adjust limits for specific server or location blocks as needed
  3. Monitor server resources and adjust as needed
  4. Use other security measures like rate limiting for large uploads

Test your configuration after making changes to make sure it works correctly.

Troubleshooting client_max_body_size Not Working

Verifying Nginx Configuration

To check for syntax errors in your Nginx configuration, run:

nginx -t

This command tests the configuration files and reports any issues.

After changing the Nginx configuration, reload it with:

sudo systemctl reload nginx


sudo nginx -s reload

To check Nginx error logs, view this file:


Look for entries about request size or 413 errors.

Investigating Server-Side Application Issues

For PHP configuration, check these settings in php.ini:

upload_max_filesize = 20M
post_max_size = 20M

Set these values to match or exceed your Nginx client_max_body_size.

Application upload limits may be in the app's configuration files or code. Check your app's documentation to adjust these limits.

Nginx and your application must work together for file uploads. Make sure that:

  1. Nginx client_max_body_size is set higher than or equal to the app's limit.
  2. Your app is set to handle the file sizes allowed by Nginx.
  3. The web server user can write to the upload directory.

Alternative Solutions for Large File Uploads

Implementing Client-Side File Splitting

Client-side file splitting, also known as chunked uploads, offers benefits for handling large file uploads:

  • Allows resumable uploads, reducing the impact of network issues
  • Improves user experience by providing progress feedback
  • Helps bypass server-side file size limits

JavaScript libraries for file splitting include:

  • Resumable.js: A library for chunked, resumable file uploads
  • Plupload: A file uploader with chunking support
  • Fine Uploader: An uploader with chunking capabilities

For server-side handling of chunked uploads:

  1. Configure your server to accept partial content uploads
  2. Implement logic to reassemble chunks into complete files
  3. Use temporary storage for chunks during the upload process
  4. Validate and process the complete file once all chunks are received

Using Reverse Proxy for File Uploads

Configuring a separate upload server can help manage large file uploads:

  1. Set up a dedicated server or container for handling file uploads
  2. Configure this server with higher resource limits for file processing
  3. Use Nginx on the main server as a reverse proxy to route upload requests

Load balancing considerations for file uploads include:

  • Distributing upload traffic across multiple backend servers
  • Using consistent hashing to route chunks of the same file to the same server
  • Implementing health checks to remove unresponsive upload servers from the pool

To use Nginx as a reverse proxy for large files:

  1. Configure Nginx to proxy requests to the upload server:
location /upload {
    proxy_pass http://upload_server;
    proxy_request_buffering off;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
  1. Adjust timeout settings to accommodate large file transfers:
proxy_connect_timeout 300s;
proxy_send_timeout 300s;
proxy_read_timeout 300s;
  1. Consider using Nginx's X-Accel-Redirect feature for serving uploaded files efficiently