How to Fix Nginx 413 Request Entity Too Large File Upload Error

When deploying web applications behind an Nginx reverse proxy, you will occasionally encounter file upload blocks. A user attempts to upload an image, PDF, or video, and the application instantly aborts, returning an HTTP status code: 413 Request Entity Too Large.

This error occurs before your backend application (such as Node.js, Python, or Go) even receives the request.

In this guide, we will analyze why Nginx blocks large HTTP payloads, configure Nginx's file limit directives, and verify that backend body sizes are aligned.

The Cause: Nginx Default Payload Safeguards

Nginx is designed to act as a shield protecting your backend web servers from malicious attacks, such as Denial of Service (DoS) attacks where hackers upload massive streams of garbage data to exhaust server memory.

To do this, Nginx enforces a default upload buffer limit called client_max_body_size.

If a client's request payload (e.g., the files inside a multipart/form-data request) exceeds this value, Nginx rejects the request immediately, returns a 413 status code, and terminates the connection.

The default limit set by Nginx is 1MB. In modern web development, almost any high-resolution image or document easily exceeds 1MB, triggering the error.

Step 1: Update the Nginx Configuration File

To resolve this issue, you must increase the client_max_body_size value inside your Nginx configuration file.

Find Your Nginx Configuration File

Depending on your OS installation, the file is typically located at:

/etc/nginx/nginx.conf
/etc/nginx/sites-available/default (or your specific site configuration block)

Add the client_max_body_size Directive

You can declare this property inside three different scope blocks:

http block: Applies the upload limit globally to all web sites hosted on this Nginx server instance.
server block: Applies the limit specifically to one domain or virtual host.
location block: Applies the limit exclusively to a specific API path (e.g., /api/uploads).

Open the file in your terminal (using sudo nano) and add the directive (replace 100M with your desired limit, e.g., 100 Megabytes):

# Setting the limit inside the http context (global)
http {
    # ...
    client_max_body_size 100M;
    # ...
}

Alternatively, to configure it inside a specific server block:

server {
    listen 80;
    server_name example.com;

    # Override for this specific domain only
    client_max_body_size 50M;

    location / {
        proxy_pass http://localhost:3000;
    }

    # Override for uploads endpoint specifically
    location /upload {
        client_max_body_size 250M;
        proxy_pass http://localhost:3000;
    }
}

Step 2: Test and Reload Nginx

After saving your configuration adjustments, you must verify the file syntax before reloading Nginx. If there is a typo in your configuration, reloading will crash your live web server.

Test Configuration Syntax

Run the syntax check command in your host terminal:

sudo nginx -t

If the syntax is correct, your console will output:

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

Reload the Nginx Service

Once the test passes, reload Nginx to apply the configurations smoothly without interrupting active user connections:

# Reload configurations
sudo systemctl reload nginx
# Or:
sudo service nginx reload

Step 3: Check Backend Application Body Limits

If users still encounter 413 exceptions after updating Nginx, your backend application framework is likely rejecting the body size as well.

Ensure your application middleware is configured to accept larger payloads:

Node.js (Express with body-parser):

// Set json and urlencoded upload limits
app.use(express.json({ limit: '100mb' }));
app.use(express.urlencoded({ limit: '100mb', extended: true }));

PHP (php.ini settings):

upload_max_filesize = 100M
post_max_size = 100M

Conclusion

The Nginx "413 Request Entity Too Large" upload failure is caused by Nginx's default 1MB request buffer. To resolve this error, edit your site's Nginx configuration to add the client_max_body_size directive, verify the syntax using nginx -t, reload the system service using systemctl reload nginx, and ensure backend body parser parameters are aligned.