Nginx client_max_body_size Explained: Configuration, Upload Limits, and Best Practices

Introduction

The client_max_body_size directive specifies the maximum allowed size of an HTTP request body that Nginx accepts from a client.

This setting is commonly used to control file upload limits and protect servers from excessively large requests. If a client sends a request that exceeds the configured limit, Nginx immediately rejects it and returns the 413 Request Entity Too Large error.

Understanding how this directive works is essential for websites that allow users to upload files, including images, videos, documents, and application packages.

This guide explains how client_max_body_size works, how to configure it, recommended values, and common configuration mistakes.

Test Environment

Operating System : AlmaLinux 10
PHP Version      : PHP 8.3
Web Server       : Nginx
PHP-FPM          : Enabled
Architecture     : x86_64
Last Tested      : July 2026

What Is client_max_body_size?

When a client uploads data, Nginx first checks the size of the HTTP request body.

If the request exceeds the configured limit, Nginx rejects the request before forwarding it to PHP-FPM or another upstream server.

Example:

http {
    client_max_body_size 50M;
}

In this example, the maximum upload size is 50 MB.

Any request larger than 50 MB is rejected with an HTTP 413 status code.

How It Works

Client Upload
      │
      ▼
Nginx
      │
      ▼
Check Request Size
      │
 ┌────┴────┐
 │         │
Within     Too Large
Limit      │
 │          ▼
 ▼      Return 413
Forward
to PHP-FPM

Unlike PHP configuration directives, Nginx performs this check before the request reaches the application.

Default Behavior

If the directive is not explicitly configured, the default limit is:

1M

This default is sufficient for small forms but is often too restrictive for applications that support file uploads.

Configuration Scope

The directive can be configured in multiple contexts.

Global:

http {
    client_max_body_size 50M;
}

Per virtual host:

server {
    client_max_body_size 100M;
}

Per location:

location /upload {
    client_max_body_size 500M;
}

More specific configuration overrides broader settings.

Check the Current Configuration

Search the configuration files:

grep -R client_max_body_size /etc/nginx

Example output:

client_max_body_size 50M;

Change client_max_body_size

Open the configuration file.

sudo nano /etc/nginx/nginx.conf

Example:

http {
    client_max_body_size 100M;
}

Save the file.

Test the Configuration

Always validate the configuration before reloading Nginx.

sudo nginx -t

Expected output:

nginx: the configuration file syntax is ok

nginx: configuration file test is successful

Reload Nginx

Apply the changes.

sudo systemctl reload nginx

Verify:

sudo systemctl status nginx

Expected output:

Active: active (running)

Relationship with PHP

A common misconception is that increasing client_max_body_size alone is enough.

For PHP applications, the following directives must also allow uploads of the desired size.

| Directive              | Purpose                                     |
| ---------------------- | ------------------------------------------- |
| `client_max_body_size` | Maximum upload accepted by Nginx            |
| `upload_max_filesize`  | Maximum size of an individual uploaded file |
| `post_max_size`        | Maximum size of the entire POST request     |

Example:

Nginx
client_max_body_size = 100M
↓
PHP
upload_max_filesize = 100M
post_max_size = 110M

If any of these limits is lower than the upload size, the upload will fail.

Recommended Values

| Application      | Suggested Value |
| ---------------- | --------------- |
| Personal website |             10M |
| Blog             |             20M |
| WordPress        |             64M |
| Laravel          |             64M |
| File sharing     |       100M–500M |
| Video upload     |           500M+ |

Choose a value appropriate for your application's actual upload requirements.

Common Issues

413 Request Entity Too Large

This is the most common error.

Example:

client_max_body_size 1M;

Trying to upload:

photo.jpg

5 MB

Result:

413 Request Entity Too Large

Increase the configured limit and reload Nginx.

PHP Still Rejects the Upload

Suppose Nginx allows:

client_max_body_size 100M;

but PHP is configured as:

upload_max_filesize = 8M

post_max_size = 8M

The upload still fails because PHP imposes a smaller limit.

Both Nginx and PHP must be configured consistently.

Setting an Excessively Large Limit

Example:

client_max_body_size 10G;

While technically valid, unnecessarily large limits may expose the server to resource exhaustion or abuse if other safeguards are not in place.

Configure upload limits according to real business requirements rather than choosing the largest possible value.

Best Practices

Configure upload limits according to your application's needs.

Keep client_max_body_size, upload_max_filesize, and post_max_size consistent.

Test uploads after changing the configuration.

Validate the configuration using nginx -t before reloading.

Avoid unnecessarily large upload limits unless they are genuinely required.

Conclusion

The client_max_body_size directive controls the maximum size of HTTP request bodies accepted by Nginx. It plays a key role in file upload handling and is often the first setting to check when encountering the 413 Request Entity Too Large error.

For PHP applications, this directive should always be configured together with upload_max_filesize and post_max_size to ensure consistent upload limits across the entire request handling process. Proper tuning helps improve usability while protecting the server from unnecessarily large requests.