Il server Minecraft lagga: trovare le cause e risolverle

"Il server lagga" è il messaggio più frequente nel sistema di ticket di qualunque gestore di game server e allo stesso tempo il più inutilizzabile. Dietro quest'unica frase si nascondono almeno tre problemi tecnici completamente diversi, che non hanno nulla a che vedere l'uno con l'altro e che si risolvono con mezzi altrettanto diversi. Chi tira a indovinare invece di misurare passa settimane a smanettare su view-distance e sui flag Java, mentre la causa vera è una catena di hopper impazzita nella cantina di un giocatore.

Questo articolo segue l'ordine in cui il procedimento funziona davvero: prima la distinzione, poi la misurazione, poi la causa, poi la contromisura. E alla fine la domanda che quasi tutte le guide tralasciano: da che cosa capisci che il problema è davvero risolto?

Due sintomi che danno esattamente la stessa impressione

Esistono due tipi di scatti profondamente diversi, più un terzo caso che con il server non c'entra nulla.

Il lag del server significa questo: il server non riesce più a portare a termine i suoi 20 passi di calcolo al secondo. È il mondo stesso a girare più lento. I mob restano fermi o sussultano, le fornaci ci mettono di più, i blocchi rotti ricompaiono, i supporti per armature si muovono in ritardo.

Il lag di rete significa questo: il server calcola senza problemi, ma i pacchetti tra giocatore e server impiegano troppo tempo oppure vanno persi. Il giocatore viene tirato indietro mentre corre (rubberbanding), i colpi non vanno a segno, la chat arriva in ritardo, ma i mob nei dintorni si muovono in modo perfettamente fluido.

Il lag del client è il terzo caso: troppo pochi fotogrammi al secondo sul computer del giocatore, di solito per colpa degli shader, di una distanza di visualizzazione troppo alta nel client o di troppa poca RAM assegnata. Dal server tutto questo è invisibile e lì non si può nemmeno risolvere.

La regola che vale quasi sempre: se il problema colpisce tutti insieme, è il server. Se colpisce singoli giocatori, è la linea. Un caso particolare rompe questa regola: un server completamente sovraccarico conferma anche i pacchetti di rete in ritardo e produce quindi ping più alti. Per questo si misurano sempre entrambe le cose.

Il primo test dura 60 secondi

Collegati al server via SSH e apri la console del server. Se il servizio non gira ancora in modo pulito in background, ti aiuta l'articolo Avviare automaticamente un server Minecraft.

Su Paper, Purpur e Folia dalla 1.21 in poi il profiler Spark è già incluso nel server, non c'è nulla da installare. Nel gioco oppure in console:

spark tps
spark health --memory --network

L'output di spark tps mostra quattro finestre temporali (5 secondi, 1, 5 e 15 minuti) e le durate dei tick come minimo, mediana, 95esimo percentile e massimo.

Su Vanilla puro senza plugin esiste /tick query. Il comando restituisce la frequenza obiettivo e il tempo medio di tick. In più, F3 insieme a 2 mostra agli operatori un grafico dei tick.

Spesso è la console stessa a tradire il problema. Di solito i lettori cercano proprio queste righe, alla lettera:

[Server thread/WARN]: Can't keep up! Is the server overloaded? Running 2123ms or 42 ticks behind
[Server thread/WARN]: Can't keep up! Did the system time change, or is the server overloaded? Running 2340ms behind

Questo messaggio significa semplicemente che il server ha impiegato per un passo di calcolo molto più dei 50 millisecondi consentiti e deve saltare dei tick. Un messaggio isolato dopo un riavvio o durante la generazione del mondo è normale. Uno ogni pochi minuti è un problema vero.

In parallelo controlla il lato sistema. mpstat non fa parte della dotazione di base di nessuno dei sistemi testati, arriva dal pacchetto sysstat e va installato una volta sola:

apt-get install -y sysstat procps
uptime
free -h
mpstat 1 3

Su AlmaLinux, Rocky Linux e Oracle Linux la prima riga diventa dnf -y install sysstat procps-ng iproute: lì il pacchetto che contiene free, uptime, top e vmstat non si chiama procps ma procps-ng.

Nell'output di mpstat interessa soprattutto la colonna %steal. Valori stabilmente sopra il 5 per cento significano che la macchina virtuale sta aspettando tempo di CPU occupato da un altro ospite. In quel caso non è un problema di Minecraft, ma un problema di capacità dell'hardware sottostante.

Una riserva su questi tre comandi: su un server tuo o su un VPS mostrano esattamente quello che vuoi sapere. Se invece il tuo server gira in un container, per esempio in un pannello di gioco come Pterodactyl, free, uptime, vmstat e mpstat riportano i valori del sistema host e non quelli della tua istanza. Vedi quindi carico e memoria che non ti appartengono. In quel caso fidati di quello che mostra il pannello e di spark health.

Leggere correttamente TPS e MSPT

Un server Minecraft calcola 20 tick al secondo, quindi ogni tick ha a disposizione un budget di 50 millisecondi. MSPT (millisecondi per tick) è il valore più significativo, perché mostra i problemi prima ancora che i TPS scendano. Un server con 20,0 TPS e 46 ms di MSPT gira al limite assoluto e crolla appena un altro giocatore entra in una zona nuova.

• MSPT sotto i 30 ms: sano, c'è margine.
• MSPT tra 30 e 45 ms: stretto, ma giocabile. È il momento di intervenire.
• MSPT sopra i 50 ms: i TPS scendono per forza, i giocatori se ne accorgono.

Più della media conta la distribuzione. Mediana 18 ms con massimo 900 ms significa picchi: singoli eventi costosi come il salvataggio automatico, la generazione dei chunk o un task di un plugin che scatta ogni minuto. Mediana 60 ms significa invece carico costante, quindi troppo contenuto simulato per la potenza di calcolo disponibile. Le contromisure sono completamente diverse.

Un punto che i consulenti hardware saltano volentieri: il tick principale di Minecraft gira in un unico thread. Il caricamento dei chunk e la rete sono stati spostati altrove, la simulazione del mondo vera e propria no. Un server con 32 core e prestazioni per singolo core basse è più lento con Minecraft di uno con 8 core veloci. I core in più servono soltanto quando ci girano sopra più istanze di server.

Spark: dal sospetto alla prova

Timings, per anni lo strumento standard, su Paper è passato a una modalità inattiva a partire dalla serie 1.21 e non fornisce più dati utilizzabili. Chi oggi pubblica ancora link a Timings non sta misurando nulla. Il successore si chiama Spark: su Paper è integrato, per Fabric, Forge e NeoForge esiste come mod, per Velocity e BungeeCord in una versione a parte.

Il procedimento decisivo: profila mentre il problema si sta verificando. Un profilo preso a server vuoto alle tre di notte non vale nulla.

spark profiler start --timeout 300
spark profiler stop

Per i picchi che compaiono solo ogni tanto conviene filtrare direttamente i tick cattivi:

spark profiler start --only-ticks-over 60 --timeout 600

In questo modo vengono registrati solo i tick durati più di 60 millisecondi. Sono esattamente quelli che i giocatori percepiscono. Il resto viene ignorato e non sporca il quadro.

Nella lettura del flame graph i principianti commettono quasi sempre lo stesso errore: guardano la ramificazione più profonda. La cosa giusta è guardare la larghezza delle barre subito sotto il tick del server. Una voce al 3 per cento è irrilevante, anche se scende per cento livelli. Regola pratica: un singolo plugin che supera il 15 per cento del tempo di tick è un candidato. Voci molto larghe intorno alle entità di blocco indicano redstone e hopper, voci larghe intorno al caricamento dei chunk indicano generazione del mondo.

Una nota sulla riservatezza: il report caricato è accessibile pubblicamente tramite il suo link e contiene informazioni di sistema, percorsi, parametri di avvio e l'elenco completo dei plugin. Passa il link solo a persone a cui affideresti queste informazioni. Con --save-to-file il profilo resta in locale.

I soliti colpevoli

Redstone e farm

Gli hopper sono di gran lunga i blocchi più costosi del gioco, perché ognuno di essi controlla a ogni tick se sopra di sé c'è qualcosa. Un impianto di smistamento con 400 hopper costa più tempo di calcolo di cento mob. Ci si aggiungono gli orologi a observer, che girano anche quando non c'è nessuno nei paraggi, a patto che il chunk venga simulato. Se Spark passa una quantità di tempo sospetta nelle entità di blocco, cerca proprio impianti di questo tipo.

Entità

Su Paper il comando /paper entity list elenca le entità per mondo e per tipo, comprese le coordinate del chunk. È la via più rapida verso la zona problematica. Ritrovamenti tipici: diverse migliaia di pile di oggetti in una farm di mob, un recinto di allevamento con 300 mucche, una zona dimenticata piena di frecce cadute a terra.

Contromisure sensate in spigot.yml: abbassare l'entity-activation-range per animali e mostri (per esempio gli animali da 32 a 16, i mostri da 32 a 24) e alzare leggermente il merge-radius per oggetti e sfere di esperienza, così esistono meno oggetti singoli. In paper-world-defaults.yml l'opzione entity-per-chunk-save-limit limita quanti oggetti di uno stesso tipo vengono salvati per chunk.

Caricamento dei chunk

Un giocatore con l'elytra o su un cavallo veloce costringe il server a generare in continuazione nuovo terreno. La generazione del mondo è in assoluto l'operazione singola più costosa. La stessa cosa succede alla prima entrata nel Nether o dopo un ampliamento del bordo del mondo. La soluzione non è un valore di configurazione ma la pregenerazione, ed è abbastanza importante da meritare una sezione a parte più avanti.

Plugin

Quando Spark indica un plugin, la faccenda è chiara. Se non lo fa, resta solo la ricerca per bisezione: disattiva metà dei plugin, misura e, a seconda del risultato, continua a dimezzare la metà incriminata. Con 32 plugin sono cinque riavvii invece di 32. Prima fai assolutamente un backup, perché i plugin che scrivono dati del mondo possono lasciare dietro di sé, una volta rimossi, contenuti che senza di loro non funzionano più.

Pregenerare i chunk prima che i giocatori ci camminino sopra

Questa è la singola misura più efficace di tutto l'articolo ed è anche quella che viene ignorata più spesso. Il motivo sta nel modo in cui Minecraft lavora: caricare dal disco un chunk già generato non costa quasi nulla. Generare un chunk nuovo significa invece mappa delle altezze, biomi, distribuzione dei minerali, grotte, strutture e calcolo della luce, e gran parte di tutto questo gira nel thread principale. Esattamente lì dove devono nascere anche i 20 tick al secondo.

Per questo di solito gli scatti arrivano quando qualcuno parte in volo con l'elytra o costruisce una ferrovia verso il nulla: il server genera mondo mentre allo stesso tempo dovrebbe calcolare il gioco. Chi genera il mondo una volta in anticipo fino al bordo trasforma un calcolo costoso in una semplice lettura da disco.

Chunky, lo strumento di riferimento

Chunky è il pregeneratore di uso comune oggi e gira come plugin su Paper, Spigot e Purpur, oltre che come mod su Fabric e Forge. La procedura è la stessa su tutte le piattaforme:

/chunky world world
/chunky center 0 0
/chunky radius 5000
/chunky start

Il raggio si indica in blocchi e dovrebbe corrispondere al bordo del mondo. Chunky segnala da solo l'avanzamento e la durata residua stimata; con /chunky pause e /chunky continue il lavoro si può fermare e riprendere in qualsiasi momento, anche attraverso un riavvio.

Nether e End sono mondi a sé e vanno pregenerati separatamente. Su Paper e Spigot si chiamano così di default:

/chunky world world_nether
/chunky radius 1000
/chunky start

Per il Nether basta un raggio più piccolo, perché lì un blocco corrisponde a otto blocchi nell'Overworld. Un raggio Nether di 1000 copre quindi 8000 blocchi di Overworld.

Che cosa devi mettere in conto

• Il tempo. Un raggio di 5000 blocchi corrisponde a circa 78 milioni di blocchi di superficie. A seconda dell'hardware, del modpack e del generatore di mondo ci vuole da un'ora a diversi giorni. I modpack con generatore di mondo proprio sono nettamente più lenti del Vanilla.
• Lo spazio su disco. Un mondo pregenerato occupa in fretta diversi gigabyte. Controlla prima quanto spazio libero hai, altrimenti il disco si riempie durante il lavoro e questo colpisce il server molto più duramente di qualsiasi scatto. Come controllarlo e come fare pulizia lo trovi in Disco pieno: trovare e liberare spazio.
• Il momento. Pregenera a server vuoto, non durante il normale esercizio. Durante il lavoro la frequenza di tick è pessima, come previsto, e non è un errore. Il senso dell'operazione è proprio togliere questo carico dal tempo di gioco.
• Impostare il bordo del mondo. Senza bordo prima o poi qualcuno esce dalla zona pregenerata e si ricomincia da capo. Imposta il bordo sullo stesso raggio che hai pregenerato.

Fare pulizia a posteriori

Se il mondo è già cresciuto e contiene zone dove non va più nessuno, Chunky elimina i chunk fuori dal bordo del mondo:

/chunky trim

Questo riduce sensibilmente il mondo e con esso anche i backup. Prima fai assolutamente un backup, perché i chunk cancellati vengono rigenerati alla prossima visita e tutto quello che i giocatori ci avevano costruito è perso.

Se Chunky non è un'opzione

Sui server più vecchi si trova ancora spesso WorldBorder con /wb fill. Svolge lo stesso compito, ma il progetto è quasi abbandonato da anni e per le versioni di server attuali Chunky è la scelta più affidabile. In entrambi i casi, prima dell'installazione controlla che la versione offerta corrisponda davvero a quella del tuo server.

view-distance e simulation-distance

Questi due valori in server.properties vengono confusi di continuo.

• view-distance stabilisce fino a che distanza i chunk vengono inviati al client. Costa banda e un po' di memoria.
• simulation-distance stabilisce fino a che distanza il server calcola entità, redstone e aggiornamenti dei blocchi. Costa tempo di CPU nel tick principale.

I chunk compresi tra il limite di simulazione e quello di visuale restano visibili, ma lato server sono congelati. I costi crescono in modo quadratico: con view-distance=10 sono 21 per 21, quindi 441 chunk per giocatore.

Valori di partenza collaudati per un network survival da 10 a 30 giocatori:

view-distance=8
simulation-distance=5

Se trovi ancora guide che parlano di no-tick-view-distance: questa opzione di Paper è superata. Con la 1.18 Mojang ha introdotto simulation-distance, risolvendo ufficialmente lo stesso problema. Impostare oggi il vecchio valore non produce alcun effetto.

Il prezzo dei valori bassi viene nominato di rado: con simulation-distance sotto 4 le farm AFK smettono di funzionare, gli spawn dei mob si comportano diversamente, le fornaci nel chunk vicino non proseguono e gli orologi a redstone si fermano. Se hai una community che vive di farm, qui stai risparmiando nel posto sbagliato e scambi un problema tecnico con un problema di giocatori. Procedi a passi di uno e misura dopo ogni passo.

Fare pulizia senza distruggere il mondo

Ogni intervento sui dati del mondo comincia con un backup a server spento. Nessun compromesso, nessuna eccezione:

tar -czf backup-mondo.tar.gz world world_nether world_the_end

Dopodiché vale la pena guardare la dimensione dei dati di regione:

du -sh world/region

I mondi cresciuti negli anni contengono spesso centinaia di megabyte di terreno che un singolo giocatore ha sorvolato una volta sola. Questi chunk non costano tempo di tick, ma spazio su disco, e allungano ogni salvataggio. Se lo spazio inizia a scarseggiare, ti aiuta anche l'articolo Disco pieno su Linux: fare pulizia.

Picchi regolari nell'ordine del secondo, che si presentano esattamente ogni cinque minuti, sono quasi sempre il salvataggio automatico. In bukkit.yml l'opzione ticks-per.autosave regola l'intervallo, in paper-world-defaults.yml l'opzione max-auto-save-chunks-per-tick limita quanto viene scritto per ogni tick. Un valore più basso distribuisce il carico invece di concentrarlo.

Per i piccoli server privati, dalla serie 1.21 in server.properties esiste l'opzione pause-when-empty-seconds. Se il valore è maggiore di zero, dopo quel tempo senza giocatori il server smette di simulare il mondo. Su un server root condiviso questo fa risparmiare tempo di calcolo in modo evidente.

Quando è la JVM a frenare

Se il tempo di tick resta basso in media ma sale in modo irregolare a diverse centinaia di millisecondi, spesso la colpa è del garbage collector dell'ambiente di esecuzione Java. Lo puoi verificare direttamente:

spark gcmonitor
spark heapsummary

Due errori diffusi: più heap non è automaticamente meglio, perché gli heap grandi producono pause più lunghe durante la pulizia. E l'heap non va mai scelto così grande da spingere il sistema operativo nello swap. Un server Minecraft che va in swap è irrimediabilmente lento. Controllalo con vmstat 1 5: valori costanti nelle colonne si e so sono una condanna a morte. Il contesto è spiegato nell'articolo Configurare lo swap ed evitare l'Out of Memory.

Questo messaggio è un sintomo, non una causa:

java.lang.OutOfMemoryError: Java heap space

Aumentare l'heap sposta soltanto il crash più in là, se un plugin perde memoria oppure se esistono milioni di entità.

Sulla versione di Java le distribuzioni si differenziano parecchio, ed è proprio qui che molte installazioni falliscono. Da Minecraft 1.20.5 in poi serve Java 21. Debian 12 nel repository standard porta solo OpenJDK 17 e non OpenJDK 21, Debian 13 porta 21 e 25, ma non 17. Ubuntu 22.04 e 24.04 hanno 17 e 21 nel repository. Chi deve restare su Debian 12 installa Temurin dal repository Adoptium. I passaggi li trovi in Installare Java 21 su Debian, per le versioni di server più vecchie in Installare Java 17 su Debian.

Non ricorrere al comodo pacchetto collettivo default-jre-headless. A seconda della release punta a una versione completamente diversa: Debian 13 e Ubuntu 24.04 con quello installano Java 21, Debian 12 installa Java 17, Debian 11 e Ubuntu 22.04 installano Java 11. L'installazione va a buon fine ovunque, ma sugli ultimi due il server comunque non parte. Indica quindi la versione in modo esplicito, cioè openjdk-21-jre-headless.

java -version
java -XX:+PrintFlagsFinal -version 2>/dev/null | grep -w MaxHeapSize

Il 2>/dev/null sopprime il banner di versione che la JVM scrive sull'output di errore e che altrimenti finirebbe in mezzo al risultato. E grep -w MaxHeapSize restituisce esattamente una riga, mentre la ricerca non esatta trova anche SoftMaxHeapSize.

Quando va storto e come tornare indietro

Il server si interrompe con un errore watchdog. Nel log c'è scritto in sostanza che un singolo tick è durato 60 secondi e che il server viene considerato bloccato. Non è un malfunzionamento, ma una misura di protezione contro un processo appeso in modo permanente. Lo stacktrace allegato vale oro: mostra esattamente dove il server era incastrato. Il valore max-tick-time in server.properties regola questa soglia. Disattivarlo non risolve nulla, trasforma solo il crash in un server congelato per sempre.

Dopo una modifica alla configurazione la situazione è peggiorata. È esattamente per questo che vale la regola più importante di tutta la diagnosi: una sola modifica per ogni misurazione, e annota il valore di partenza. Chi tocca contemporaneamente view-distance, entity range e flag Java, dopo non sa più che cosa abbia funzionato.

Dopo il crash il server non parte più. Di solito level.dat è danneggiato. Nella cartella del mondo c'è level.dat_old, che puoi copiarci sopra dopo aver messo da parte una copia dello stato rotto. Con i file di regione danneggiati aiuta solo il backup.

È tutto ottimizzato e continua a scattare. Allora controlla il livello sottostante: %steal in mpstat, lo swap in vmstat e la latenza del disco. Se il tempo di tick resta alto anche se Spark non mostra nessun singolo responsabile sopra il 10 per cento, allora è semplicemente troppo contenuto per prestazioni per singolo core troppo basse. Servono quindi la suddivisione su più istanze oppure più potenza di calcolo, non la prossima vite di configurazione.

Solo i giocatori hanno ping alti, il server è tranquillo. Allora il problema è la rete. Una sede con percorsi brevi verso i giocatori fa qui la differenza più grande. Per i server a Francoforte sul Meno le latenze tipiche dall'Italia e dall'Europa centrale restano nella fascia bassa a due cifre. Se i problemi compaiono all'improvviso e tutti insieme, dietro può esserci anche un attacco, vedi Proteggere il server dagli attacchi DDoS. Lato client compaiono allora messaggi di questo tipo:

Internal Exception: io.netty.handler.timeout.ReadTimeoutException
Timed out
Connection reset

Da che cosa capisci che il problema è davvero risolto

Una correzione si considera confermata solo quando regge esattamente sotto il carico che ha fatto emergere il problema. Di notte, con due giocatori, gira bene anche un server rotto. Verifica nelle ore di punta:

• spark tps mostra 20,0 nella finestra dei 15 minuti e non solo in quella dei 5 secondi.
• Il 95esimo percentile del tempo di tick sta sotto i 40 ms, il massimo sotto i 100 ms.
• 24 ore di log senza una singola riga "Can't keep up!".
• Un profilo Spark fresco non mostra più nessuna singola voce sopra il 15 per cento.
• spark gcmonitor non segnala pause sopra i 200 ms.
• I giocatori che si erano fatti sentire confermano il miglioramento nello stesso posto e nella stessa situazione di gioco.

Annota i valori prima e dopo, possibilmente con la data e la modifica effettuata ogni volta. Al prossimo calo, tra tre mesi, questa lista varrà più di qualsiasi guida, perché mostra che cosa ha già funzionato proprio sul tuo server. Se rifai il server da zero, trovi le basi giuste in Installare un server Minecraft su Debian e nella checklist per un nuovo server root.