upload_max_filesize and post_max_size values in your PHP configuration files. Additionally, adjusting the Nginx or Apache client body size limit ensures the reverse proxy does not reject the request before it reaches the application.
Understanding the Upload Bottleneck
When a user attempts to upload a file larger than the configured limit, the transfer is silently dropped or results in a generic error. On a bare metal Debian 12 server, the bottleneck is almost always at the web server or PHP layer, not the MariaDB backend. The database handles metadata storage efficiently, but the HTTP layer enforces strict size caps for security and stability reasons. If you encounter timeouts or connection resets during large transfers, these limits are the primary suspects.
Configuring PHP Limits
The first step is to modify the PHP settings that control incoming data sizes. You need to edit the main php.ini file used by your web server. On Debian 12, this is typically located at /etc/php/8.2/fpm/php.ini for PHP-FPM or /etc/php/8.2/apache2/php.ini if using Apache modules. Open the file with a text editor like nano or vim.
- upload_max_filesize: This defines the maximum size of an individual file. Set this to your desired limit, such as
50Gfor very large datasets. - post_max_size: This must be greater than
upload_max_filesize. It controls the total size of POST data. A common practice is to set this slightly higher than the upload limit, for example,51G. - max_execution_time: Large uploads take time. Increase this value (e.g., to
3600) to prevent PHP from timing out before the transfer completes. - memory_limit: Ensure this is sufficient to handle the script overhead, though it rarely needs to match the file size entirely.
After making these changes, save the file. If you are using PHP-FPM, restart the service using sudo systemctl restart php8.2-fpm. For Apache, use sudo systemctl restart apache2. Always verify the changes by creating a simple info.php file in your web root and checking the loaded configuration values.
Adjusting Web Server Proxy Settings
Even with correct PHP settings, your reverse proxy may block large requests. Most modern Nextcloud installations on Debian use Nginx. You must check the Nginx configuration file, usually found in /etc/nginx/sites-available/ or /etc/nginx/conf.d/.
Look for the client_max_body_size directive within the server or location block. By default, this is often set to 1m or 10m. Change this value to match or exceed your PHP post_max_size. For example:
server {
listen 443 ssl;
# ... other directives ...
client_max_body_size 51g;
location / {
# ... proxy pass directives ...
}
}If you are using Apache with mod_proxy, ensure that LimitRequestBody is either unset or set to a high value, as Apache’s default can also restrict payload sizes. After modifying Nginx, test the configuration with sudo nginx -t and reload it with sudo systemctl reload nginx. This step is critical because Nginx will return a 413 Request Entity Too Large error if the limit is hit before PHP ever sees the request.
Tuning Chunked Uploads
Nextcloud supports chunked uploads, which break large files into smaller pieces. This feature is enabled by default in recent versions and helps stabilize transfers over unstable connections. However, if you are experiencing specific issues with chunked uploads, you can adjust related settings in config.php. Note that you do not need to manually enable "chunked_upload" as it is controlled internally. Instead, ensure that the memcache.local and memcache.distributed settings are configured correctly if you have Redis installed, as this improves performance for locking mechanisms during concurrent uploads.
For pure stability without Redis, you can rely on the database transaction logs. If your uploads still fail, check the Nextcloud log at data/nextcloud.log for entries related to "Chunked upload" or "Locking". These logs will tell you if the issue is related to temporary file storage permissions or disk space exhaustion on the /tmp partition.
Verifying Disk Space and Permissions
A common oversight is assuming that because the server has space, the upload will succeed. Temporary files are stored in /tmp or a designated upload_tmp_dir. If your /tmp partition is small (common on systems with limited RAM), large uploads will fail even if your main data directory has terabytes of free space. Check the mount point for /tmp using df -h /tmp. If it is full, consider mounting a larger partition there or setting upload_tmp_dir in php.ini to a directory on a larger volume.
Ensure that the web server user (www-data) has write permissions to the Nextcloud data directory and the config folder. Incorrect permissions can cause silent failures where the upload starts but cannot finalize the file move. Use sudo chown -R www-data:www-data /var/www/nextcloud/data to fix ownership issues.
Optimizing Network and Timeout Settings
If you are uploading over slow networks, TCP window scaling and keep-alive settings might need adjustment. While less common on local bare metal servers, ensuring that your firewall allows sustained connections is vital. Some firewalls drop idle connections after a few minutes. Since large uploads can take hours, ensure that any intermediate load balancers or proxies support long-lived connections.
Additionally, consider enabling gzip compression for static assets to free up bandwidth for the actual file data. In Nginx, this is handled by the gzip module, which should be active by default. This optimization reduces the load on your network interface, allowing more consistent throughput for large binary transfers.
Frequently Asked Questions
Why does my upload fail immediately with a 413 error?
This error indicates that the web server (Nginx or Apache) rejected the request before PHP processed it. You must increase the client_max_body_size in Nginx or LimitRequestBody in Apache to match your PHP limits. Restarting the web server after changing these settings is required for them to take effect.
Do I need Redis to upload large files successfully?
No, Redis is not strictly required for large file uploads to function. It primarily improves performance by handling distributed locking and caching. Without Redis, Nextcloud uses the database for locking, which is slower but fully functional for most users. Focus on PHP and web server limits first before adding caching layers.
How do I check if my /tmp partition is too small?
Run the command df -h /tmp in your terminal. Look at the "Use%" column and the available space. If the partition is nearly full or significantly smaller than the files you are trying to upload, change the upload_tmp_dir in php.ini to a location with more free space.
What is the difference between upload_max_filesize and post_max_size?
upload_max_filesize limits the size of a single uploaded file, while post_max_size limits the total size of all POST data, including file uploads and form fields. post_max_size must always be larger than upload_max_filesize, otherwise, PHP will reject the entire request even if the file itself is under the limit.
Can I monitor the progress of a large upload in real-time?
Nextcloud’s web interface shows progress bars, but for debugging, you can monitor the server-side activity. Use tail -f data/nextcloud.log while attempting an upload to see real-time events. Additionally, monitoring disk I/O with iostat or iotop can help confirm that the server is actively writing data during the transfer.