Il Capitolo I, «Out of the Breach», è arrivato il 12 ottobre 2026 con l'Update 7, e molti amministratori si sono trovati davanti allo stesso problema al riavvio: un server che non parte o mod che non si caricano più. Questa guida non spiega come installare le mod: ti dà un metodo di diagnosi completo, dal primo messaggio di errore alla soluzione, proteggendo il tuo mondo a ogni passaggio.

Perché il Capitolo I rompe alcune mod

L'Update 7 non è un semplice aggiornamento di contenuti. Tocca tre livelli da cui dipendono le mod:

• Il protocollo di rete ha cambiato versione. Client e server devono coincidere: un server rimasto all'Update 6 rifiuta i giocatori aggiornati, e viceversa. Nessuna mod aggira questa regola.
• L'API del server è stata profondamente rivista. Le note per gli sviluppatori citano, per esempio, TickProcedure.onTick, la cui firma è cambiata, WorldChunk, che non contiene più un World, e DurabilityOperator, rinominato ComparisonOperator. Una mod Java (file .jar) compilata per l'Update 6 che usa questi elementi può rifiutarsi di caricarsi o andare in crash durante la partita.
• Gli asset del gioco sono cambiati. Le note della pre-release dell'Update 7 segnalano chiavi rinominate (ChargeAcceleration diventa ChargeAccelerationDistance), campi dell'aliante spostati in Template_Glider, identificatori che non si risolvono più (Spectre_Void) e perfino file PNG rinominati, come Spiwer_Web_Full.png, ora Spider_Web_Full.png. Un pack che punta a un elemento scomparso può fallire la validazione.

Altro punto importante: il formato di salvataggio è cambiato. Un mondo viene convertito automaticamente la prima volta che lo carica un server con il Capitolo I, e un mondo convertito non può più essere aperto da una versione precedente. La conversione è a senso unico.

Prima di tutto: il backup

Arresta il server e copia almeno:

• la cartella universe/ (i tuoi mondi);
• l'intera cartella mods/, con le cartelle di configurazione delle mod;
• i file config.json, permissions.json, whitelist.json e bans.json.

Annota anche l'elenco esatto delle tue mod con la loro versione: ti servirà per confrontarlo con le pagine degli autori. Se hai già avviato con il Capitolo I, conserva comunque una copia dello stato attuale prima di modificare qualcosa, e non riavviare il server di continuo sperando che l'errore sparisca.

Passo 1: leggere i log nel posto giusto

Console e log dicono quasi sempre quale mod sta dando problemi, purché tu guardi nel posto giusto:

Situazione	Dove guardare
Server dedicato o in hosting	La console del pannello, poi la cartella logs/ del server (un file per avvio, con data e ora nel nome)
Mondo in singolo o condiviso dal gioco	UserData/Saves/<mondo>/logs
Problema lato client (gioco)	UserData/logs

Apri il log dell'ultimo avvio e risali fino al primo errore: i successivi sono spesso solo conseguenze. Cerca Error, Exception e Failed, oltre al nome di ciascuna delle tue mod. Su Linux basta un comando per filtrare:

grep -inE "error|exception|failed" logs/*.log | head -n 40

Su Windows, PowerShell fa lo stesso:

Select-String -Path .\logs\*.log -Pattern "error","exception","failed" | Select-Object -First 40

Un messaggio come Failed to load manifest file! indica una mod il cui manifest.json manca, è nel posto sbagliato o non è leggibile. Uno stack trace Java che cita una classe o un metodo non trovato (per esempio NoSuchMethodError) segnala quasi sempre una mod Java compilata per la vecchia API.

Passo 2: classificare il tipo di errore

Trovata la riga incriminata, classificala. Il rimedio dipende dalla categoria.

Sintomo	Causa probabile	Cosa fare
Il server si ferma all'avvio citando una mod	Mod Java incompatibile con la nuova API	Installare la versione della mod per il Capitolo I o rimuoverla temporaneamente
Errore di validazione di un asset (chiave sconosciuta, ID non trovato)	Pack che fa riferimento a un elemento rinominato o eliminato	Attendere o installare l'aggiornamento del pack
La mod si carica ma un effetto non funziona più	Chiave rinominata che genera solo un avviso	Segnalarlo all'autore, controllare gli avvisi nel log
Mod saltata per una dipendenza	Dipendenza mancante o troppo vecchia	Installare o aggiornare la dipendenza
Comportamenti strani, oggetti duplicati	Due versioni della stessa mod in mods/	Tenere un solo file
I giocatori non riescono a connettersi	Versioni di client e server diverse	Allineare la versione e il canale di aggiornamento (patchline)

Passo 3: eliminare i duplicati

È la causa più banale e la più trascurata. Aggiornando una mod si carica il nuovo file senza cancellare il vecchio, e la cartella mods/ finisce per contenere due versioni della stessa mod. Elenca la cartella e cerca nomi simili:

ls -1 mods/ | sort

Se vedi, per esempio, MiaMod-1.4.2.jar e MiaMod-1.5.0.jar, tieni solo la versione per il Capitolo I. Attenzione anche alle mod presenti sia come pack .zip sia come cartella decompressa: ne deve restare solo una.

Passo 4: controllare le dipendenze

Ogni mod dichiara ciò di cui ha bisogno nel suo manifest.json, nella radice del .jar, dello .zip o della cartella del pack. Due campi contano:

• Dependencies: le mod obbligatorie, nel formato Gruppo:Nome con un intervallo di versioni. Se una manca o è fuori intervallo, la mod non si carica.
• OptionalDependencies: le mod facoltative. Se mancano, la mod si carica comunque.

{
  "Group": "Esempio",
  "Name": "MiaMod",
  "Version": "1.5.0",
  "ServerVersion": "...",
  "Dependencies": {
    "Esempio:LibComune": ">=2.0.0"
  },
  "OptionalDependencies": {}
}

La trappola tipica dopo un grande aggiornamento: la mod principale ha già la sua versione per il Capitolo I, ma la sua libreria no. In quel caso la mod principale non ti serve a nulla finché la dipendenza non viene aggiornata. Nelle pagine di download, la scheda delle relazioni indica quali dipendenze sono obbligatorie. Il campo ServerVersion, quando è compilato, indica anche per quale versione del server è stata pubblicata la mod: confrontalo con il risultato del comando /version.

Passo 5: rimuovere temporaneamente la mod colpevole

Se non esiste nessuna versione compatibile, bisogna decidere. Due casi molto diversi:

La mod non aggiunge blocchi né oggetti

Interfaccia, minimappa, comandi di amministrazione, strumenti di gestione: puoi rimuoverla senza rischi. Arresta il server, sposta il file in una cartella a parte (per esempio mods-disattivate/) invece di cancellarlo, poi riavvia. Puoi anche disattivarla nella sezione Mods del config.json del server, sempre a server fermo: il server riscrive i suoi file di configurazione mentre gira e una modifica fatta a caldo può andare persa.

La mod aggiunge blocchi, oggetti o creature

Qui serve prudenza. Se la rimuovi, i blocchi che ha piazzato possono apparire come sconosciuti o sparire, e gli oggetti interessati possono andare persi dagli inventari. Ogni mondo conserva inoltre nella propria configurazione l'elenco delle mod di cui ha bisogno: se ne manca una, il mondo può rifiutarsi di caricarsi. Prova quindi sempre la rimozione su una copia del mondo prima di toccare quello principale. Spesso la scelta migliore è lasciare il server spento, o aprire un mondo provvisorio, in attesa dell'aggiornamento della mod.

Per individuare in fretta la mod colpevole in un lungo elenco, il metodo delle metà è il più rapido: togli metà delle mod, avvia e ripeti con la metà che contiene l'errore. Con 30 mod bastano cinque avvii. La documentazione della community cita anche un'opzione di avvio, --ignore-broken-mods, che lascia partire il server nonostante una mod con errori per poterla identificare; verifica con --help che la tua versione la supporti prima di fidarti, e non usarla mai sul mondo principale senza backup.

Passo 6: attendere (e seguire) l'aggiornamento della mod

Per le mod Java, la correzione arriva quasi sempre dall'autore, che deve ricompilare la mod per la nuova API. Qualche buona abitudine:

• controlla la pagina di ogni mod e cerca espressamente «Chapter 1» o «Update 7» nel registro delle modifiche;
• il browser delle mod integrato nel gioco mostra a colpo d'occhio quali mod della tua libreria sono state aggiornate;
• non scaricare una «versione corretta» pubblicata da sconosciuti: un file .jar esegue codice sul tuo server;
• se una mod è abbandonata, cerca un'alternativa mantenuta invece di tenerti una versione rotta.

Tabella di compatibilità per tipo di mod

Non tutte le mod corrono lo stesso rischio dopo il Capitolo I. Questa tabella ti aiuta a decidere da dove cominciare:

Tipo di mod	Rischio dopo l'Update 7	Cosa controllare
Pack solo grafico (texture, suoni)	Basso	File rinominati nel gioco base
Pack di contenuti (blocchi, oggetti, NPC, alianti)	Medio	Chiavi e ID rinominati o eliminati
Mod Java per server (.jar)	Alto	Una versione compilata per il Capitolo I
Libreria condivisa da altre mod	Alto	Aggiornata prima di tutte le mod che ne dipendono
Mod che genera strutture o mondi	Da medio ad alto	Test su una copia del mondo, compatibilità con il nuovo formato di salvataggio

Una buona notizia, già che ci siamo: con l'Update 7 una mod può contenere mondi interi, e un mondo creato da una mod sopravvive alla rimozione di quella mod.

Errori che non dipendono dalle mod

Prima di dare la colpa alle tue mod, escludi queste cause, anch'esse legate al Capitolo I:

• Codice di uscita 11 su un server installato in proprio: i dati del server si trovano nella cartella di installazione del launcher. Sposta il server in una cartella dedicata.
• Avviso su MaxViewRadius: la distanza visiva ora ha un limite di 32 chunk. Il server parte comunque, ma correggi il valore in config.json.
• Giocatori rifiutati: client e server non sono sulla stessa versione o sullo stesso canale di aggiornamento.

Checklist rapida

1. Arrestare il server e fare il backup di universe/, mods/ e dei file di configurazione.
2. Leggere il primo errore dell'ultimo log.
3. Eliminare i duplicati da mods/.
4. Aggiornare le dipendenze prima delle mod che le usano.
5. Rimuovere temporaneamente le mod senza versione per il Capitolo I, provando prima su una copia quelle che aggiungono blocchi.
6. Riavviare, verificare che il server sia in esecuzione e fare una prova con un solo giocatore prima di riaprire a tutti.

FAQ

Posso tornare all'Update 6 se le mie mod non funzionano più?

Solo con un backup fatto prima dell'aggiornamento. Un mondo aperto da un server con il Capitolo I viene convertito e non può più essere letto da una versione precedente.

La mia mod è aggiornata ma il server continua a non partire. Perché?

Controlla le sue dipendenze e verifica che in mods/ non sia rimasta una vecchia copia della stessa mod. Basta una libreria ferma alla versione dell'Update 6 per bloccare il caricamento.

I texture pack sono coinvolti?

Raramente, ma alcuni file del gioco base sono stati rinominati. Se un pack grafico sostituisce un file che ha cambiato nome, quella sostituzione non verrà più applicata.

Quanto bisogna aspettare l'aggiornamento di una mod?

Dipende interamente dall'autore e non c'è una scadenza garantita. Segui la pagina o il registro delle modifiche della mod; se non mostra attività, prepara un'alternativa.