Lunedì mattina, ore 8:30. Il team di sviluppo arriva in ufficio e scopre che la piattaforma di comunicazione interna è offline. Qualcuno ha deciso di aggiornare l'ambiente di esecuzione durante il weekend, pensando che passare all'ultima versione di Java avrebbe garantito prestazioni migliori. Invece, i log sono pieni di un errore criptico che recita Mattermost Unsupported Class File Major Version 68. Ho visto questa scena ripetersi in decine di aziende, dalle startup ai grandi gruppi industriali. Il sistemista di turno prova a riavviare il servizio, poi il container Docker, poi l'intero server, ma nulla cambia. Il costo di questo fermo non si misura solo nei minuti di inattività, ma nella frustrazione dei programmatori che non possono coordinarsi e nel panico del management che vede i processi bloccati. Questo errore specifico indica una discrepanza tra la versione di Java usata per compilare i plugin o i componenti e quella usata per farli girare, e se non sai dove mettere le mani, rischi di passare ore a inseguire la variabile d'ambiente sbagliata.
L'illusione che l'ultima versione di Java sia sempre la scelta migliore
C'è un'idea sbagliata che circola tra chi gestisce infrastrutture: l'idea che aggiornare Java all'ultima versione disponibile sia un'azione priva di rischi. Quando incontri il problema relativo a Mattermost Unsupported Class File Major Version 68, significa che stai cercando di eseguire bytecode compilato per Java 24 (che corrisponde alla major version 68) su una Java Virtual Machine (JVM) più vecchia. Spesso succede perché uno sviluppatore ha compilato un plugin custom usando un JDK sperimentale o troppo recente, mentre il server di produzione è rimasto, correttamente, su una versione Long Term Support (LTS).
La soluzione non è aggiornare il server alla cieca. Se il tuo server Mattermost gira su Java 17 o 21, e gli dai in pasto un file compilato per la versione 68, il sistema si rifiuta di partire. Invece di forzare l'aggiornamento della JVM sul server, che potrebbe rompere altre dipendenze del sistema operativo, devi allineare il processo di build. Ho visto aziende perdere intere giornate cercando di far digerire a Ubuntu versioni di Java non ancora stabili, quando sarebbe bastato cambiare una riga nel file di configurazione di Maven o Gradle per compilare verso un target compatibile.
Il rischio delle dipendenze esterne non verificate
Spesso l'errore non arriva dal tuo codice, ma da una libreria di terze parti che hai scaricato con troppa leggerezza. Se il repository da cui peschi i plugin ha iniziato a distribuire file compilati con JDK 24, ti ritroverai bloccato. La strategia corretta in questi casi è mantenere un ambiente di staging che specchi esattamente la produzione. Se in staging non hai la versione 68 di Java, non devi permettere che nessun file con quel formato entri nella pipeline di deploy.
Mattermost Unsupported Class File Major Version 68 e il disastro dei container disallineati
Un altro scenario classico che ho incontrato riguarda l'uso di Docker. Immagina questo: il tuo Dockerfile usa un'immagine di base generica, magari openjdk:latest. Sabato notte viene rilasciata una nuova versione taggata come latest che include il JDK 24. Il tuo processo di CI/CD ricostruisce l'immagine, la pusha nel registro e il sistema va in crash perché il resto della tua infrastruttura o i plugin caricati esternamente non sono pronti. Usare il tag latest è un errore da principianti che costa caro.
Per risolvere questo pasticcio, devi bloccare le versioni. Non scrivere mai FROM openjdk. Scrivi FROM openjdk:21-slim o la versione specifica che hai testato. Se il tuo sistema segnala Mattermost Unsupported Class File Major Version 68, significa che c'è un'incoerenza tra l'immagine che usi per compilare (magari un'immagine di build molto recente) e quella che usi per l'esecuzione. La coerenza tra le fasi della pipeline è l'unico modo per evitare di svegliarsi con il server rotto.
Come identificare il file colpevole
Quando il server non parte, non limitarti a leggere l'ultima riga del log. Devi scorrere verso l'alto e trovare lo stack trace completo. Lì troverai il nome del file .class o del file .jar che sta causando il conflitto. Spesso è un plugin di integrazione con sistemi legacy o un bot personalizzato. Una volta identificato il file, usa il comando javap -v NomeFile.class | grep major per confermare la versione. Se leggi 68, hai trovato il colpevole.
L'errore di sottovalutare il file di configurazione del plugin
Molti pensano che basti cambiare la versione di Java nel sistema operativo per sistemare tutto. Non è così. Ho lavorato con un cliente che aveva installato tre versioni diverse di Java sul server, creando un groviglio di link simbolici che nemmeno lui riusciva più a seguire. Il servizio partiva usando Java 11, mentre i plugin richiedevano la 17, e nel frattempo qualcuno aveva inserito un componente compilato per la versione 68.
La soluzione professionale non è aggiungere versioni di Java, ma pulire. Devi avere una sola versione LTS installata e configurare esplicitamente la variabile JAVA_HOME. Se un componente richiede una versione troppo alta, quel componente non è adatto alla tua infrastruttura. Punto. Non si adatta l'infrastruttura a un singolo plugin, a meno che non ci sia una ragione tecnica enorme dietro. Di solito, è solo pigrizia dello sviluppatore che non ha impostato il target di compilazione corretto.
Confronto tra un approccio amatoriale e uno professionale
Vediamo come cambia la gestione di questo problema tra chi improvvisa e chi sa cosa sta facendo.
Il sistemista inesperto nota l'errore nel log. La sua prima reazione è cercare su Google come installare l'ultima versione di Java disponibile. Trova un repository PPA non ufficiale, lo aggiunge al server di produzione e installa Java 24. Il server Mattermost riparte, ma improvvisamente altre utility di sistema scritte in Java smettono di funzionare o i vecchi plugin iniziano a dare errori di memoria perché i parametri della JVM sono cambiati tra le versioni. Ha risolto un sintomo, ma ha creato un'instabilità cronica nel server. Ha passato quattro ore a configurare un ambiente che ora è una "special snowflake", ovvero un sistema unico e impossibile da replicare se dovesse rompersi di nuovo.
Il professionista, invece, identifica subito che il numero 68 corrisponde a Java 24. Capisce che quel file è "troppo avanti" per un server di produzione stabile. Invece di toccare il server, va alla radice. Prende il codice sorgente del plugin che causa il problema, lo inserisce in una pipeline di build che usa un JDK 21 con il flag --release 21. Ricompila il tutto, ottenendo un file compatibile. Sostituisce il plugin, riavvia il servizio e il sistema torna online in quindici minuti. Il server rimane pulito, standard e facile da manutenere. Non ha installato nulla di nuovo sulla macchina, ha solo corretto l'artefatto sbagliato.
Il falso mito della retrocompatibilità totale
Si tende a credere che Java sia sempre retrocompatibile. Anche se è vero che una JVM nuova può eseguire codice vecchio, il contrario non è mai vero. Se provi a caricare una classe compilata con una versione major superiore a quella della JVM, riceverai sempre un errore fatale. Nel contesto di questi sistemi di messaggistica aziendale, questo accade spesso durante le migrazioni o quando si caricano plugin scaricati da forum o repository non ufficiali.
Ho visto amministratori di sistema tentare di "patchare" il bytecode per cambiare il numero della versione major manualmente. Non farlo. È una perdita di tempo colossale che porta a errori di runtime imprevedibili e crash improvvisi del thread. Se un file richiede la versione 68, significa che potrebbe usare feature del linguaggio o API della libreria standard che nelle versioni precedenti semplicemente non esistono. Se lo forzi, il server potrebbe partire, ma esploderà alla prima chiamata a una funzione non supportata.
Gestione dei permessi e delle variabili d'ambiente nascoste
C'è un dettaglio che molti trascurano: dove punta effettivamente il comando java quando viene eseguito dall'utente che fa girare il servizio. Spesso, l'amministratore testa il comando come root e vede che la versione è corretta. Ma il servizio Mattermost gira sotto un utente dedicato, magari mattermost, che ha un .bashrc o un profilo diverso.
- Controlla quale binario Java sta usando il servizio specifico guardando il file di unità di Systemd.
- Verifica che non ci siano versioni di Java "nascoste" dentro cartelle come
/opto/usr/local/binche precedono il Java di sistema nelPATH. - Assicurati che l'ambiente di esecuzione non stia ereditando variabili sporche da una sessione precedente.
Dalla mia esperienza, il 30% di questi problemi si risolve semplicemente definendo il percorso assoluto del binario Java nell'eseguibile di avvio, invece di affidarsi al sistema per trovarlo. È un trucco banale, ma evita che un aggiornamento di sistema cambi silenziosamente la versione di default mandando tutto all'aria.
Controllo della realtà
Smettiamola di pensare che gestire un server di comunicazione sia un compito da "set and forget". Se lavori con tecnologie che permettono l'estensibilità tramite plugin, devi accettare che la gestione delle dipendenze diventerà il tuo lavoro principale. Non esiste una bacchetta magica. Se vedi versioni di classe che non corrispondono alla tua JVM, significa che il tuo processo di gestione del software è rotto.
Per avere successo non ti serve l'ultima versione di ogni strumento. Ti serve la coerenza. Se decidi di restare su Java 17, ogni singolo pezzo del tuo ecosistema deve essere allineato. Il desiderio di usare l'ultima luccicante funzione di Java 24 ti costerà caro in termini di stabilità se non hai le risorse per aggiornare l'intera infrastruttura. In un ambiente di produzione, la noia è un pregio. Se il tuo server non dà errori per mesi, stai facendo un buon lavoro. Se invece ogni settimana devi combattere con versioni di classi non supportate, significa che stai correndo troppo senza guardare dove metti i piedi. Prendi una versione LTS, blocca i tuoi Dockerfile, verifica ogni plugin prima di installarlo e smetti di inseguire versioni sperimentali che non portano alcun valore reale al business. Il tempo risparmiato non dovendo gestire crash improvvisi è denaro guadagnato per l'azienda e salute mentale guadagnata per te.
