Come rimuovere il file .maintenance dopo un aggiornamento bloccato

Durante gli aggiornamenti WordPress crea un file temporaneo chiamato .maintenance. Finché il file è attivo, WordPress evita di caricare normalmente il sito mentre sostituisce core, plugin, temi o traduzioni. Se il processo termina correttamente, il file viene rimosso automaticamente.

La procedura seguente spiega come rimuovere il file .maintenance WordPress tramite cPanel o SFTP e quali verifiche eseguire subito dopo.

Come riconoscere la modalità manutenzione bloccata

Il messaggio tipico è:

Momentaneamente non disponibile per manutenzione programmata. Riprovare tra un minuto.

Può comparire dopo:

• aggiornamento del core;
• aggiornamento di plugin o temi;
• chiusura della pagina durante il processo;
• timeout PHP;
• spazio disco o inode esauriti;
• errore di rete o download;
• processo terminato per risorse insufficienti.

Prima di eliminare il file

1. attendi almeno alcuni minuti;
2. verifica che la schermata di aggiornamento non stia ancora avanzando;
3. non avviare un secondo aggiornamento;
4. annota il componente che stavi aggiornando;
5. crea una copia del file o un backup se devi modificare altri dati.

Eliminare .maintenance mentre un aggiornamento è ancora in corso può rendere il sito accessibile durante la sostituzione dei file.

Metodo 1: rimuovere .maintenance da cPanel

1. accedi a cPanel;
2. apri File → Gestione file;
3. seleziona Impostazioni in alto a destra;
4. attiva Mostra file nascosti (dotfiles);
5. apri la cartella principale di WordPress, per esempio public_html o la document root del dominio;
6. individua .maintenance;
7. scaricane una copia facoltativa;
8. elimina solamente quel file;
9. ricarica il sito in una finestra anonima.

Il file si trova nella stessa cartella che contiene normalmente wp-config.php, wp-admin, wp-content e wp-includes.

Metodo 2: rimuovere .maintenance tramite SFTP o FTPS

Configura il client per mostrare i file nascosti. Apri la directory principale di WordPress e cancella .maintenance. Se non lo vedi:

• aggiorna l’elenco dei file;
• verifica di essere nella document root corretta;
• abilita la visualizzazione dei dotfile;
• controlla maiuscole e nome esatto;
• verifica che il file non sia già stato rimosso automaticamente.

Metodo 3: rimuovere il file da terminale

Solo se disponi di accesso SSH e conosci il percorso:

cd /home/UTENTE/public_html
ls -la .maintenance
rm -- .maintenance

Prima di eseguire rm, il comando ls -la deve mostrare il file nella cartella corretta. Non utilizzare wildcard e non eseguire comandi ricorsivi.

Se .maintenance non esiste

La schermata può provenire dalla cache del browser, LiteSpeed, Cloudflare o da un plugin di manutenzione. Procedi così:

1. apri una finestra anonima;
2. controlla la document root corretta;
3. esegui purge della cache LiteSpeed;
4. svuota la cache CDN, se utilizzata;
5. controlla plugin di manutenzione o coming soon;
6. verifica il codice HTTP e gli header;
7. consulta i log PHP.

Non svuotare tutte le cache prima di aver verificato che l’aggiornamento sia davvero terminato.

Che cosa controllare dopo la rimozione

La scomparsa del messaggio non garantisce che il sito sia integro. Controlla:

• homepage e pagine interne;
• accesso a /wp-admin/;
• versione del componente aggiornato;
• avvisi nella schermata Aggiornamenti;
• plugin e tema attivi;
• registro errori;
• moduli, carrello e funzioni dinamiche;
• spazio disco e Resource Usage.

Messaggio “Un aggiornamento automatico di WordPress non è riuscito a completarsi”

Se la bacheca mostra ancora questo avviso, aggiorna la pagina dopo aver rimosso .maintenance e controllato i file. Se l’aggiornamento core è incompleto, segui la procedura manuale ufficiale o ripristina un punto funzionante.

Non modificare direttamente le opzioni del database soltanto per nascondere l’avviso: è necessario verificare il motivo del fallimento.

Se compare un errore critico

Un aggiornamento può aver lasciato file incompatibili o parziali. Consulta la guida Errore critico WordPress e controlla:

• error_log;
• wp-content/debug.log;
• plugin o tema indicato;
• versione PHP;
• memoria e timeout;
• integrità dei file core.

Se il sito torna ogni volta in manutenzione

Il problema può essere causato da:

• aggiornamento automatico che riparte;
• cron bloccato;
• plugin di gestione aggiornamenti;
• permessi che impediscono la rimozione del file;
• spazio insufficiente;
• processo PHP terminato;
• più nodi o copie del sito non sincronizzate.

Controlla data e ora di creazione del nuovo file. Se ricompare, non limitarti a cancellarlo: individua quale processo lo genera.

Controlla che il file appartenga all’installazione corretta

In un account multidominio possono esistere più installazioni WordPress e più file .maintenance. Prima di eliminarlo confronta il percorso con la document root mostrata in cPanel e verifica che nella stessa cartella sia presente il wp-config.php del dominio interessato. Eliminare il file da un’altra installazione non risolve il problema e può interrompere un aggiornamento legittimo su un secondo sito.

Cache, proxy e schermate di manutenzione personalizzate

Il messaggio standard WordPress è diverso dalle pagine generate da plugin coming soon, manutenzione del tema o proxy esterni. Controlla il sorgente HTML e gli header: una risposta con elementi grafici personalizzati, cookie specifici o intestazioni Cloudflare può non dipendere da .maintenance.

Se il file è assente e la pagina continua a comparire, prova l’URL con una query temporanea non sensibile, verifica da rete mobile e controlla la cache dell’origine. Non disattivare Cloudflare o LiteSpeed in modo permanente; utilizza un bypass o purge mirato soltanto per il test.

Conserva una traccia dell’aggiornamento interrotto

Prima di riprovare, annota le date di modifica di wp-admin, wp-includes e della cartella del componente interessato. Queste informazioni aiutano a capire se i file sono stati sostituiti parzialmente. Salva anche il messaggio mostrato dalla bacheca e le righe di log dello stesso intervallo.

Se l’aggiornamento automatico riparte subito, disattiva temporaneamente soltanto il meccanismo o il plugin che lo avvia, non tutti i cron del sito. Dopo la correzione riattiva la pianificazione e verifica che non venga ricreato un nuovo file di manutenzione.

Permessi consigliati

Il file deve essere gestibile dall’utente dell’account. Non impostare permessi globalmente scrivibili come 777. Se WordPress non riesce a creare o rimuovere file, verifica proprietà e permessi con l’assistenza invece di allargarli indiscriminatamente.

Come prevenire il problema

• aggiorna un componente alla volta;
• mantieni spazio e inode liberi;
• non chiudere la finestra durante l’operazione;
• non eseguire importazioni o backup contemporaneamente;
• verifica compatibilità PHP;
• crea un backup prima degli aggiornamenti importanti;
• esegui test in staging per siti complessi.

La procedura per rimuovere il file .maintenance WordPress deve sempre essere seguita da una verifica dell’aggiornamento e dei log.

Quando aprire un ticket Xlogic

Apri un ticket se .maintenance ricompare, non puoi eliminarlo, l’aggiornamento ha lasciato il sito danneggiato o non riesci a individuare la document root.

Indica dominio, data e ora, componente aggiornato, percorso controllato, messaggio e righe del log. Non inviare password.

Fonti tecniche ufficiali

• WordPress: Failed Updates
• WordPress: Dashboard Updates
• WordPress: FAQ Troubleshooting

Domande frequenti sul file .maintenance