Tema WordPress rotto dopo un aggiornamento
Cos’è un tema WordPress “rotto” dopo un aggiornamento e perché succede
Un tema “rotto” dopo un aggiornamento può manifestarsi in due modi molto diversi: un errore fatale che blocca il sito del tutto, oppure un sito che si carica ma ha perso funzionalità, sezioni o stili personalizzati che prima c’erano. In entrambi i casi la causa più frequente non è un difetto del nuovo aggiornamento in sé, ma il modo in cui erano state fatte le personalizzazioni precedenti.
Personalizzazioni fatte direttamente nel tema principale
La causa più comune è aver modificato in passato i file del tema principale — tramite l’editor di file integrato in WordPress o via FTP — senza usare un child theme. Un aggiornamento del tema sostituisce integralmente i file del tema con la nuova versione: qualsiasi modifica fatta direttamente su quei file (una funzione personalizzata, uno stile CSS aggiunto, una sezione di codice nel functions.php) viene sovrascritta e sparisce, anche se l’aggiornamento in sé si completa senza errori. Se qualcos’altro sul sito — un plugin, uno snippet, un widget — dipendeva da una di quelle personalizzazioni (ad esempio richiamava una funzione definita solo lì), il risultato può essere un errore fatale “Call to undefined function”, non solo una perdita estetica.
Funzione in conflitto tra vecchio e nuovo codice del tema
Una causa meno comune, ma frequente per chi ha aggiunto snippet di codice tramite un plugin dedicato (invece che nel tema stesso), riguarda una funzione che nella nuova versione del tema viene dichiarata con lo stesso nome di una già definita altrove: PHP non permette di dichiarare due volte la stessa funzione, e il risultato è un errore fatale “Cannot redeclare function” che blocca l’intero sito.
Cache con file della versione precedente
Una causa da citare, ma meno grave delle precedenti, riguarda la cache: se un plugin di cache o un CDN continua a servire i file CSS o JS della versione precedente del tema, il sito può apparire visivamente “rotto” (stili mancanti, layout diverso) anche se l’aggiornamento dei file è avvenuto correttamente lato server.
Come capire la causa: leggere i segnali
Il primo passaggio è distinguere tra un sito che non si carica affatto (errore fatale) e un sito che si carica ma manca di qualcosa rispetto a prima: sono due situazioni con percorsi di intervento diversi.
Errore fatale o sito visivamente incompleto
Se il sito mostra una schermata bianca o un messaggio di errore critico, il problema riguarda quasi certamente del codice PHP che non trova più una funzione attesa, o una funzione dichiarata due volte: è un problema bloccante che va risolto prima di qualsiasi altra cosa. Se invece il sito si carica ma sembra “diverso” — una sezione personalizzata non compare più, uno stile è cambiato, un widget custom è sparito — è più probabile che una personalizzazione fatta nei file del tema sia stata sovrascritta dall’aggiornamento, senza generare un errore bloccante.
Verificare il log degli errori
Se il sito mostra un errore fatale, attiva temporaneamente WP_DEBUG e WP_DEBUG_LOG in wp-config.php (o chiedi all’hosting il log degli errori PHP già attivo): il file debug.log indicherà il nome esatto della funzione mancante o duplicata e il file in cui l’errore si verifica, permettendo di capire subito se il problema riguarda una personalizzazione persa o un conflitto tra due dichiarazioni della stessa funzione.
| Sintomo osservabile | Causa probabile |
|---|---|
| Schermata bianca o errore critico su tutto il sito | Funzione mancante o duplicata a causa di personalizzazioni sovrascritte o in conflitto |
| Il log riporta “Call to undefined function” | Una personalizzazione nel tema principale, sovrascritta dall’aggiornamento, era richiamata altrove |
| Il log riporta “Cannot redeclare function” | Una funzione aggiunta via snippet/plugin ha lo stesso nome di una nella nuova versione del tema |
| Sito che si carica ma manca una sezione o uno stile personalizzato | Personalizzazione fatta direttamente nei file del tema, sovrascritta dall’aggiornamento |
| Layout o stili “vecchi” nonostante l’aggiornamento sia completato | Cache di pagina o CDN che serve ancora i file CSS/JS della versione precedente |
Risolvere il tema rotto: recuperare le personalizzazioni in un child theme
Per il caso più comune — personalizzazioni sovrascritte perché fatte nel tema principale — la soluzione corretta non è solo far ripartire il sito, ma anche evitare che lo stesso problema si ripresenti al prossimo aggiornamento.
Ripristinare temporaneamente la versione precedente per recuperare le modifiche
Se hai un backup precedente all’aggiornamento, ripristina temporaneamente (anche solo in locale o su una copia del sito, non necessariamente in produzione) la versione precedente del tema per recuperare il codice delle personalizzazioni perse — la funzione custom, lo snippet CSS, la modifica al functions.php. Se non hai un backup, verifica se il codice era stato annotato altrove (un documento, un altro ambiente di sviluppo): senza una copia da qualche parte, la personalizzazione va ricostruita da zero.
Creare un child theme e spostare lì le personalizzazioni
Crea un child theme (una cartella separata che eredita lo stile e le funzioni dal tema principale, ma i cui file non vengono mai toccati dagli aggiornamenti del tema principale) e sposta lì le personalizzazioni recuperate: il functions.php del child theme per le funzioni custom, un file style.css del child theme per gli stili aggiuntivi. Da questo momento, un aggiornamento del tema principale non cancellerà più queste modifiche, perché vivono in un file separato che WordPress non sovrascrive mai.
Aggiornare di nuovo il tema principale e verificare
Attiva il child theme appena creato, verifica che il sito mostri di nuovo le personalizzazioni recuperate, e solo a questo punto assicurati che il tema principale sia sull’ultima versione disponibile. Controlla il sito sia da loggato sia in una scheda anonima, per escludere che la cache del browser mostri ancora una versione intermedia della pagina.
Errore fatale immediato per una funzione duplicata o rimossa
Se il sito mostra subito un errore critico dopo l’aggiornamento e il log conferma “Cannot redeclare function” o “Call to undefined function”, il primo intervento non è creare un child theme, ma disattivare temporaneamente lo snippet o il plugin di codice personalizzato coinvolto (identificabile dal nome della funzione nel log), per far tornare il sito online subito. Solo dopo, con il sito di nuovo funzionante, puoi valutare con calma se rinominare la funzione in conflitto o spostare la personalizzazione in un child theme, per evitare che lo stesso conflitto si ripresenti al prossimo aggiornamento del tema.
Non riesci a risolvere? Intervento tecnico a distanza
Se non sei sicuro di quale personalizzazione sia stata persa, se il log degli errori non è chiaro, o se il sito resta bloccato anche dopo aver provato a disattivare snippet o plugin sospetti, continuare a intervenire su un tema già compromesso rischia di far perdere anche le tracce del codice originale da recuperare. In questi casi è possibile richiedere una verifica diretta dell’accesso FTP/SFTP e del pannello hosting: si individua la causa esatta nel log degli errori, si recupera il codice perso da un backup se disponibile, e si struttura tutto in un child theme per proteggerlo dai prossimi aggiornamenti.
Domande frequenti sul tema WordPress rotto dopo un aggiornamento
Perdo per sempre le personalizzazioni sovrascritte da un aggiornamento? Non necessariamente: se hai un backup precedente all’aggiornamento, il codice delle personalizzazioni è ancora recuperabile da lì. Senza backup, invece, va ricostruito da zero se non è stato salvato altrove.
Cos’è esattamente un child theme e perché protegge dagli aggiornamenti? È un tema separato che eredita stile e funzioni dal tema principale ma ha i propri file, che gli aggiornamenti del tema principale non toccano mai: per questo è il posto corretto dove tenere qualsiasi personalizzazione.
Posso evitare il problema disattivando gli aggiornamenti automatici del tema? Puoi ridurre il rischio di essere colto di sorpresa, ma il problema di fondo (personalizzazioni nei file del tema principale) resta comunque presente al primo aggiornamento manuale che deciderai di installare.
Come faccio a sapere se il problema riguarda il tema o un plugin? Il log degli errori (debug.log) indica il file coinvolto nell’errore: se il percorso include la cartella del tema attivo, il problema è nel tema; se include la cartella di un plugin, il problema è lì.
Serve sempre attivare WP_DEBUG per capire la causa? È il modo più rapido per avere il nome esatto della funzione coinvolta nell’errore; in alternativa, molti hosting mettono a disposizione un log degli errori PHP già attivo dal pannello, senza dover modificare wp-config.php.
Vuoi risolverlo con un intervento diretto? Se il tema resta rotto dopo l’aggiornamento e non sei sicuro di come recuperare le personalizzazioni perse, è possibile richiedere una verifica diretta dell’accesso al sito: si individua la causa esatta, si recupera quanto possibile e si mette al sicuro il tutto in un child theme. → Richiedi assistenza tecnica.