Il file non si carica: upload_max_filesize, post_max_size e il limite che vince

Prima cosa da fare: guarda il messaggio esatto

Se il sito è giù e il cliente preme "carica" senza risultato, non perdere tempo a leggere tutta la guida: guarda il messaggio di errore. Risponde già a metà della domanda.

• Pagina bianca o 413 Request Entity Too Large: è il server web (Nginx), non PHP.
• Messaggio PHP "The uploaded file exceeds the upload_max_filesize directive": è upload_max_filesize.
• Form che si svuota, $_POST e $_FILES vuoti, nessun errore visibile: quasi sempre post_max_size superato.
• Errore dell'applicazione (WordPress, Moodle, un CMS) con un numero diverso da quello che hai impostato in PHP: c'è un quarto limite, quello dell'applicazione stessa.

I quattro limiti, in ordine di frequenza con cui bloccano davvero un upload

1. upload_max_filesize (PHP)

Limita la dimensione del singolo file caricato. Il manuale PHP indica che upload_max_filesize int: The maximum size of an uploaded file. Il valore di default è "2M".

Come si capisce se è questa la causa: il messaggio PHP lo nomina esplicitamente, oppure nel codice di errore dell'upload trovi UPLOAD_ERR_INI_SIZE.

2. post_max_size (PHP)

Limita la dimensione totale della richiesta POST, non solo il file: campi di testo, intestazioni multipart e il file insieme. Il manuale PHP è netto: To upload large files, this value must be larger than upload_max_filesize. Se la richiesta intera supera questo valore, If the size of post data is greater than post_max_size, the $_POST and $_FILES superglobals are empty.

Questo è il caso subdolo: niente errore visibile, il form sembra "non fare niente". Se vedi $_FILES vuoto senza nessun messaggio, controlla prima post_max_size.

3. client_max_body_size (Nginx)

È il limite del server web sulla dimensione dell'intero corpo della richiesta, prima ancora che PHP la veda. Dalla documentazione ufficiale nginx.org: this is the maximum size of a client request body. If this size is exceeded, Nginx returns a 413 Request entity too large HTTP error. Il default è 1m.

Se vedi un 413 e la pagina non è nemmeno quella del tuo CMS ma una pagina di errore generica di Nginx, il colpevole è questo, non PHP.

4. Il limite dell'applicazione

Molte applicazioni (WordPress, Moodle, gestionali, pannelli di upload personalizzati) aggiungono un proprio tetto, indipendente da PHP e dal server web, spesso configurabile da pannello o da codice. Se dopo aver alzato tutti e tre i limiti sopra l'errore resta identico con lo stesso numero, è l'applicazione che sta imponendo il suo.

Come si cambiano, sistema per sistema

Su un VPS con Ubuntu 24.04, Nginx e PHP-FPM

Per PHP-FPM modifica il file ini della versione di PHP in uso (il percorso cambia a seconda della versione installata, tipicamente sotto /etc/php/8.x/fpm/php.ini):

upload_max_filesize = 64M
post_max_size = 72M

Riavvia PHP-FPM con il comando (sostituisci 8.3 con la tua versione):

sudo systemctl restart php8.3-fpm

Per Nginx, nel blocco server o http del file di configurazione del sito:

client_max_body_size 72M;

Verifica la sintassi e ricarica:

sudo nginx -t
sudo systemctl reload nginx

Nota sulla sintassi: il valore di client_max_body_size va scritto senza spazio fra numero e unità e con la m minuscola nell'esempio ufficiale (1m), mentre PHP usa la M maiuscola (64M): sono due parser diversi, non è un errore se li vedi scritti in modo diverso.

Su cPanel

Su cPanel i valori di PHP si cambiano da MultiPHP INI Editor, che scrive direttamente nel file ini della versione di PHP assegnata al dominio: lì si imposta sia upload_max_filesize sia post_max_size. cPanel di solito usa Apache con mod_php o PHP-FPM dietro Apache, quindi in genere non c'è un client_max_body_size di Nginx da gestire separatamente, a meno che il provider non abbia aggiunto Nginx come reverse proxy davanti ad Apache: in quel caso il limite Nginx esiste comunque e va cercato nella configurazione del proxy, non nel pannello utente.

Su Plesk

Su Plesk i due valori PHP si cambiano da Domini > nomedominio > PHP Settings (o "Dashboard > PHP" nelle versioni più recenti), dove compaiono entrambi i campi: per una specifica dominio: Log in to Plesk, Go to Domains > example.com > PHP Settings, modificando upload_max_filesize e post_max_size. Il valore di default in Plesk per upload_max_filesize è 2 MB.

Se il dominio è servito da Nginx (alcune configurazioni Plesk usano Nginx come reverse proxy davanti ad Apache, altre lo usano come server diretto per PHP-FPM), esiste anche qui un limite equivalente a client_max_body_size, gestito dal pannello come "Maximum allowed HTTP request body size" nelle impostazioni Nginx del dominio o del piano di servizio: Go to Service Plans, Set the Maximum allowed HTTP request body size (also known as client_max_body_size) to the same value that you used for post_max_size and upload_max_filesize.

L'errore tipico: cambiarne uno solo

Il caso più frequente che si vede in assistenza: si alza upload_max_filesize a 500M, il file continua a non salire, e il sistemista giura di aver "sistemato il problema". Non l'ha sistemato: ha spostato il collo di bottiglia su uno degli altri tre limiti. Un thread della community PHP lo riassume bene: $_FILES will be empty if a user attempts to upload a file greater than post_max_size in your php.ini, post_max_size should be >= upload_max_filesize in your php.ini.

La regola pratica, valida ovunque: i quattro limiti vanno alzati insieme, e in quest'ordine di grandezza — client_max_body_size (Nginx) ≥ post_max_size (PHP) > upload_max_filesize (PHP), con un margine per l'overhead del multipart, più l'eventuale limite dell'applicazione alzato a parte.

Caso pratico: caricare un video o un backup da 500 MB

Per un file da 500 MB servono, come minimo:

upload_max_filesize = 512M
post_max_size = 550M
client_max_body_size 550M;

Il margine tra upload_max_filesize e post_max_size serve a coprire i campi del form e le intestazioni multipart che viaggiano insieme al file. Su Plesk, per upload di queste dimensioni, il pannello suggerisce direttamente valori in gigabyte: file_uploads = on, upload_max_filesize = 3500M, post_max_size = 3500M. Instead of "3500M" you can use gigabytes, for example "4G".

Ricorda anche memory_limit di PHP: il manuale consiglia che memory_limit should be larger than post_max_size, altrimenti PHP esaurisce la memoria prima ancora di validare il file.

Come si verifica che è risolto

1. Controlla i valori effettivamente attivi, non quelli scritti nel file: su riga di comando, php -i | grep -E "upload_max_filesize|post_max_size|memory_limit" (su Ubuntu/PHP-FPM) legge la configurazione caricata davvero dal processo PHP in esecuzione, non un file che magari non viene letto.
2. Per Nginx, verifica la direttiva effettivamente in uso con sudo nginx -T | grep client_max_body_size: se compare più di una riga, vince quella del blocco più specifico (location batte server, server batte http).
3. Fai una prova reale con un file della dimensione limite +10%, non solo con un file piccolo: un file da 2 MB passa anche con i default di fabbrica, e non prova nulla sul limite che ti interessa davvero.
4. Se il file resta bloccato dopo aver alzato tutti e tre i livelli (PHP, server web, applicazione), il problema può essere a monte, lato fornitore: su molti hosting condivisi il provider impone un tetto non modificabile dal pannello cliente. In quel caso, apri un ticket indicando dimensione esatta del file, messaggio di errore completo, e i valori attuali di upload_max_filesize, post_max_size e client_max_body_size che hai già provato: senza questi dati l'assistenza non può distinguere un limite di piattaforma da un errore di configurazione.