Nginx 413 Request Entity Too Large: Fixing `client_max_body_size` on macOS Local Development

Resolve Nginx 413 'Request Entity Too Large' on macOS local dev. Adjust `client_max_body_size` and PHP-FPM settings for successful file uploads.

When working on a web application locally on macOS, especially one involving file uploads, you might encounter an "Nginx 413 Request Entity Too Large" error. This frustrating issue typically arises when you attempt to upload a file that exceeds Nginx's configured maximum allowed size for client requests. While a common problem in production environments, it's particularly frequent during local development where larger test files are often used without prior server configuration adjustments. This guide will walk you through diagnosing and resolving this specific Nginx 413 error within your macOS local development setup.

Symptom & Error Signature

The most immediate symptom of this error is your web browser displaying a generic "413 Request Entity Too Large" page when you try to submit a form containing a large file upload.

You'll also observe specific entries in your Nginx error logs, providing more detail.

Browser Output Example:

413 Request Entity Too Large

Nginx Error Log Example (e.g., /opt/homebrew/var/log/nginx/error.log):

2023/10/26 14:35:01 [error] 7890#0: *123 client intended to send too large body: 12345678 bytes, client: 127.0.0.1, server: localhost, request: "POST /upload HTTP/1.1", host: "localhost:8080"

Nginx Access Log Example (e.g., /opt/homebrew/var/log/nginx/access.log):

127.0.0.1 - - [26/Oct/2023:14:35:01 +0000] "POST /upload HTTP/1.1" 413 199 "-" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36"

Root Cause Analysis

The "413 Request Entity Too Large" error is directly 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). Its default value is typically 1m (1 Megabyte).

Why this directive exists:

• DDoS Protection: It helps prevent Denial of Service attacks by limiting the size of requests an attacker can send, thereby consuming excessive server resources.
• Resource Management: Prevents legitimate but overly large file uploads from monopolizing server memory and processing power, ensuring stability for other users.
• Security: Limits the potential for malicious large file uploads.

In a local development environment, hitting this limit is common because developers often test with larger dummy files or media assets without considering the default Nginx restrictions, which are optimized for general public-facing production scenarios rather than specific development needs.

Another crucial aspect, especially when using PHP applications, is the interaction between Nginx's client_max_body_size and PHP's upload_max_filesize and post_max_size directives. For a file upload to succeed, the Nginx limit and both PHP limits must be greater than or equal to the size of the file being uploaded. If Nginx denies the request first, PHP's limits won't even be evaluated.

Step-by-Step Resolution

To resolve the Nginx 413 error, you need to adjust the client_max_body_size directive in your Nginx configuration. If you're using a PHP application, you'll likely also need to modify PHP's upload limits.

1. Locate Your Nginx Configuration File(s)

On macOS, if Nginx was installed via Homebrew (the most common method), your primary configuration file is usually located at:

• /opt/homebrew/etc/nginx/nginx.conf (for Apple Silicon Macs)
• /usr/local/etc/nginx/nginx.conf (for Intel Macs)

Inside this main nginx.conf file, you might find include directives that point to other configuration files or directories (e.g., include servers/*; or include http/*.conf;). These included files often contain server-specific configurations (virtual hosts) for your local development projects.

Use grep to quickly search for your current client_max_body_size setting, or to confirm its absence:

grep -r "client_max_body_size" /opt/homebrew/etc/nginx/

2. Modify client_max_body_size in Nginx Configuration

You can place the client_max_body_size directive in three main contexts within your Nginx configuration:

• http block: Applies globally to all virtual hosts/servers defined within this Nginx instance.
• server block: Applies only to a specific virtual host.
• location block: Applies only to a specific URL path within a server block.

For local development, placing it in the http block is often convenient if all your projects require larger uploads. For production or more specific needs, placing it in a server or location block is recommended for better control.

1. Open your Nginx configuration file using a text editor. For example:

   nano /opt/homebrew/etc/nginx/nginx.conf
   # or if you have a specific site config like
   # nano /opt/homebrew/etc/nginx/servers/myproject.conf
   

2. Add or modify the client_max_body_size directive. We'll set it to 50m (50 Megabytes) as a common example, but adjust this value to suit your specific needs. Common units are k (kilobytes) and m (megabytes).

   Example: Placing in the http block (global):

   http {
       client_max_body_size 50m; # Set max client body size to 50MB
       # ... other http configurations ...
       
       include servers/*; # Or other include directives for your virtual hosts
   }
   

   Example: Placing in a server block (per virtual host):

   server {
       listen 80;
       server_name myproject.test;
       root /Users/youruser/Sites/myproject/public;
       index index.php index.html index.htm;
   
       client_max_body_size 50m; # Set max client body size for this project
   
       # ... other server configurations ...
   }
   

   Example: Placing in a location block (per path):

   server {
       listen 80;
       server_name myproject.test;
       root /Users/youruser/Sites/myproject/public;
   
       location /upload_big_files {
           client_max_body_size 100m; # Specific for this upload path
           # ... other location configurations ...
       }
   
       location / {
           # Default client_max_body_size for other paths (inherits from server or http block)
           # ...
       }
   }
   

Choose the appropriate scope for your client_max_body_size directive. For local development, setting it in the http block is quick, but for production, consider setting it per server or location block for fine-grained control and security.

3. Verify Nginx Configuration Syntax

Before reloading Nginx, always test your configuration for syntax errors. This prevents Nginx from failing to start due to a malformed configuration.

sudo nginx -t

• Successful output:

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

• Error output: If there are errors, Nginx will point to the line number and file where the issue occurred. Correct these errors before proceeding.

4. Reload Nginx Service

Once your configuration syntax is verified, reload Nginx to apply the changes.

For Nginx installed via Homebrew on macOS:

sudo brew services restart nginx

If you're managing Nginx via Docker (common in local dev):

Navigate to your docker-compose.yml directory and restart the Nginx service:

docker-compose restart nginx
# Or, if running a single container:
docker restart <your_nginx_container_name>

For standard Linux environments (e.g., Ubuntu/Debian) using systemd:

While this guide focuses on macOS local dev, if you're working on a similar issue in a Linux environment, you would typically use:

sudo systemctl reload nginx

5. (Optional but Recommended) Adjust PHP-FPM Limits

If your application uses PHP and involves file uploads, Nginx is only one part of the equation. PHP itself has limits on upload size. You'll need to adjust two directives in your php.ini file to match or exceed your Nginx client_max_body_size.

1. Locate your php.ini file: On macOS with Homebrew PHP, this is typically at /opt/homebrew/etc/php/<php_version>/php.ini (e.g., /opt/homebrew/etc/php/8.2/php.ini).

2. Open php.ini for editing:

   nano /opt/homebrew/etc/php/8.2/php.ini # Adjust version as needed
   

3. Find and modify the following directives:

   upload_max_filesize = 50M
   post_max_size = 50M
   

   Set these values equal to or greater than your client_max_body_size in Nginx. It's generally a good practice for post_max_size to be equal to or slightly larger than upload_max_filesize as it accounts for the entire POST request body, which includes file data and other form fields.

It is crucial that post_max_size is at least equal to upload_max_filesize. If post_max_size is smaller, uploads will fail silently without an Nginx 413 error, often resulting in empty $_FILES arrays in PHP.

4. Restart PHP-FPM service: After modifying php.ini, you must restart the PHP-FPM service for changes to take effect.

   sudo brew services restart php
   

   If you're using Docker for PHP-FPM, restart that container:

   docker-compose restart php-fpm
   # Or, if running a single container:
   docker restart <your_php_fpm_container_name>
   

6. Test the Upload

After making all necessary changes and restarting both Nginx (and PHP-FPM if applicable), try uploading your large file again. The upload should now proceed successfully without the 413 error. If you still encounter issues, double-check all configuration files for typos, ensure correct service restarts, and review your Nginx and PHP-FPM error logs for new clues.