Erreur UnsupportedClassVersionError : diagnostiquer et installer Java 25 pour son serveur Minecraft

Votre serveur Minecraft s'arrête en une seconde avec un message qui commence par java.lang.UnsupportedClassVersionError ? Rien de grave : ce n'est ni votre monde ni votre configuration, c'est un désaccord entre la version de Java qui lance le serveur et celle pour laquelle le programme a été compilé. Ce guide vous apprend à lire l'erreur, à trouver le Java réellement utilisé et à installer Java 25 proprement, quel que soit votre environnement.

Lire le message d'erreur en 30 secondes

Voici la forme typique de l'erreur au démarrage d'un serveur récent :

Error: LinkageError occurred while loading main class net.minecraft.bundler.Main
    java.lang.UnsupportedClassVersionError: net/minecraft/bundler/Main has been compiled
    by a more recent version of the Java Runtime (class file version 69.0),
    this version of the Java Runtime only recognizes class file versions up to 65.0

Trois informations suffisent pour poser le diagnostic :

• La classe citée (ici net/minecraft/bundler/Main) : elle vous dit qui est trop récent. Une classe en net/minecraft, io/papermc ou org/bukkit désigne le serveur lui-même. Un autre nom de paquet désigne en général un plugin ou un mod.
• Le premier numéro (« compiled by… class file version 69.0 ») : la version de Java exigée.
• Le second numéro (« recognizes class file versions up to 65.0 ») : la version de Java utilisée en ce moment.

Table de correspondance class file version et Java

Chaque version de Java produit un numéro de « class file version » précis. Voici ceux que l'on croise sur les serveurs Minecraft :

Dans l'exemple ci-dessus, le serveur exige Java 25 (69) mais tourne sous Java 21 (65). La règle est simple : il faut un Java au moins aussi récent que le premier numéro. Un Java plus récent que nécessaire fonctionne en général très bien.

Quelle version de Java pour quelle version de Minecraft ?

Voici les versions minimales exigées par le serveur Minecraft Java Edition, valables pour Vanilla, Spigot, Paper et Purpur :

• 1.17 : Java 16 ;
• 1.18 à 1.20.4 : Java 17 ;
• 1.20.5 à 1.21.11 : Java 21 ;
• 26.1 et suivantes : Java 25.

Java 25 est une version LTS (support à long terme) : en l'installant, vous couvrez à la fois les serveurs 26.x et les anciennes versions qui demandaient Java 17 ou 21.

Les trois situations qui déclenchent l'erreur

1. Le serveur est trop récent pour votre Java

C'est le cas le plus courant depuis l'arrivée des versions 26.x : le jar du serveur a été mis à jour, mais Java est resté en 21. La classe citée appartient au serveur et le premier numéro vaut 69. Solution : installer Java 25 et lancer le serveur avec.

2. Un plugin ou un mod est trop récent

Votre serveur démarre, mais la console affiche l'erreur au chargement d'un plugin, avec un nom de classe qui ne ressemble pas à Minecraft. Le plugin a été compilé pour une version de Java plus récente que celle du serveur. Deux options : passer le serveur sous Java 25 (sans risque pour une 1.21, qui fonctionne aussi sous Java 25), ou installer une version plus ancienne du plugin compilée pour votre Java.

3. Le message inverse : « Unsupported class file major version 69 »

Cette variante est trompeuse. Elle ne vient pas de Java lui-même mais d'un outil qui lit les classes (bibliothèque de transformation de code utilisée par certains chargeurs de mods ou anciens plugins). Elle signifie que cet outil est trop ancien pour comprendre les classes de Java 25. Ici, installer Java 25 ne sert à rien : il faut mettre à jour le chargeur de mods ou le plugin concerné, ou revenir à la version de Java prévue pour votre version de Minecraft.

Trouver le Java réellement utilisé

Erreur classique : java -version affiche 25, mais le serveur plante quand même. C'est que votre script de démarrage n'utilise pas le même Java que votre terminal. Vérifiez sous Linux :

# Version du Java par défaut
java -version

# Binaire réellement appelé par la commande java
readlink -f "$(command -v java)"

# Toutes les versions installées (Debian / Ubuntu)
update-alternatives --list java

# Variable parfois utilisée par les scripts
echo "$JAVA_HOME"

Ouvrez ensuite votre script de démarrage (start.sh, unité systemd, configuration de screen ou tmux) et regardez la ligne de lancement. Si elle commence par un chemin complet, du type /usr/lib/jvm/java-21-…/bin/java, c'est ce Java-là qui est utilisé, quelle que soit la version par défaut du système.

Sous Windows, ouvrez une invite de commandes et tapez :

where java
java -version

Si where java renvoie plusieurs chemins, c'est le premier qui gagne. Un ancien Java installé avant le nouveau peut ainsi passer devant lui dans la variable PATH.

Installer Java 25 selon votre environnement

Il existe plusieurs distributions d'OpenJDK gratuites et reconnues : Eclipse Temurin (projet Adoptium), Amazon Corretto, Microsoft Build of OpenJDK… Elles sont équivalentes pour un serveur Minecraft. Les exemples ci-dessous utilisent Temurin.

Debian et Ubuntu

Le paquet temurin-25-jdk est distribué par le dépôt APT officiel d'Adoptium. Ajoutez d'abord ce dépôt en suivant la page Linux de la documentation d'installation d'Adoptium (import de la clé GPG, puis création du fichier /etc/apt/sources.list.d/adoptium.list), puis installez Java 25 :

sudo apt update
sudo apt install -y temurin-25-jdk

Choisissez ensuite Java 25 comme version par défaut, si plusieurs versions cohabitent :

sudo update-alternatives --config java
java -version

Fedora, RHEL et dérivés

Après avoir déclaré le dépôt Adoptium dans /etc/yum.repos.d/ (voir la même documentation), l'installation se fait en une ligne :

sudo dnf install temurin-25-jdk

Windows

Le plus simple est le gestionnaire de paquets winget, intégré à Windows 10 et 11. Dans un terminal ouvert en administrateur :

winget install EclipseAdoptium.Temurin.25.JDK

Fermez et rouvrez le terminal, puis vérifiez avec java -version. Vous pouvez aussi télécharger l'installateur MSI depuis le site d'Adoptium : pensez à cocher l'option qui met à jour la variable PATH.

macOS

Avec Homebrew :

brew install openjdk@25

Homebrew indique à la fin de l'installation la commande à exécuter pour rendre ce Java visible par le système : suivez-la, puis vérifiez avec java -version.

Docker

Si votre serveur tourne dans un conteneur, c'est l'image qui fixe la version de Java, pas la machine hôte. Basez votre image sur une version 25, par exemple eclipse-temurin:25-jre, ou, si vous utilisez une image Minecraft prête à l'emploi, choisissez son étiquette Java 25. Reconstruisez puis recréez le conteneur : un simple redémarrage garde l'ancienne image.

Sur un panel d'hébergement

Sur un serveur hébergé avec un panel, vous n'installez rien vous-même : la version de Java dépend de l'« image » ou du « runtime » choisi dans les paramètres de démarrage du serveur. Sélectionnez l'image Java 25, enregistrez, puis redémarrez complètement le serveur (arrêt puis démarrage). Si l'image Java 25 n'apparaît pas pour votre type de serveur, ouvrez un ticket auprès de votre hébergeur plutôt que de bricoler la ligne de démarrage.

Lancer le serveur avec le bon Java, durablement

Une fois Java 25 installé, sécurisez votre lancement pour ne plus dépendre de la version par défaut du système, qui peut changer lors d'une mise à jour de paquets. Appelez Java par son chemin complet dans votre script :

#!/bin/sh
# start.sh : chemin à adapter à votre installation
JAVA=/usr/lib/jvm/temurin-25-jdk-amd64/bin/java
"$JAVA" -version
"$JAVA" -Xms4G -Xmx4G -jar server.jar --nogui

La ligne "$JAVA" -version affiche la version utilisée en tête de la console : au prochain plantage, vous saurez immédiatement quel Java était en cause. Pour trouver le chemin exact, utilisez la commande update-alternatives --list java vue plus haut.

Si votre serveur est géré par systemd, modifiez la ligne ExecStart de l'unité avec ce même chemin complet, puis rechargez la configuration :

sudo systemctl daemon-reload
sudo systemctl restart minecraft

Plusieurs serveurs, plusieurs versions de Java

Vous gardez un vieux serveur en 1.16 à côté d'un serveur 26.x ? Aucun problème : plusieurs versions de Java peuvent être installées en même temps. Attribuez à chaque serveur son propre chemin de Java dans son script de démarrage, et ne changez pas la version par défaut du système au hasard. Pour les très anciennes versions (1.12 et antérieures), restez sur Java 8 : certaines refusent de démarrer avec un Java récent.

Checklist de dépannage rapide

1. Relevez les deux numéros de class file version et la classe citée dans l'erreur.
2. Convertissez-les avec la table : version exigée et version utilisée.
3. Déterminez le coupable : le serveur lui-même, un plugin ou un mod.
4. Vérifiez le Java réellement appelé par le script de démarrage, pas seulement celui du terminal.
5. Installez Java 25 si nécessaire, puis pointez le script, l'unité systemd, l'image Docker ou l'image du panel vers lui.
6. Redémarrez complètement et lisez la console : la ligne de version de Java doit afficher 25.

FAQ

Faut-il installer le JDK ou le JRE ?

Le JRE suffit pour faire tourner un serveur. Le JDK contient en plus les outils de compilation et sert par exemple à compiler Spigot avec BuildTools. En cas de doute, le JDK couvre tous les usages.

Java 25 fait-il tourner un serveur 1.21 ?

Oui. Un Java plus récent que le minimum exigé fonctionne en général sans difficulté, ce qui permet d'installer Java 25 avant même de changer de version de Minecraft.

Les joueurs doivent-ils installer Java 25 ?

Non. Le lanceur officiel de Minecraft fournit automatiquement la bonne version de Java au jeu. Le problème ne concerne que les serveurs et les lanceurs tiers configurés avec un Java fixe.

L'erreur persiste après l'installation de Java 25 : que faire ?

Dans neuf cas sur dix, le script de démarrage pointe encore vers l'ancien Java. Ajoutez la ligne -version décrite plus haut pour le vérifier. Si la console affiche bien Java 25 et que l'erreur parle de « major version 69 », c'est le cas 3 : un plugin ou un chargeur de mods à mettre à jour.