Pterodactyl : résoudre les erreurs d'installation SteamCMD

Vous lancez l'installation d'un serveur Rust, Valheim, ARK ou CS2 depuis Pterodactyl, la barre tourne, puis le serveur reste bloqué. Dans la grande majorité des cas, le problème vient de l'étape SteamCMD, celle qui télécharge les fichiers du jeu. Voici comment lire l'erreur et la corriger, cas par cas.

1. Ce qui se passe pendant l'installation

Quand vous créez un serveur, Wings, le service de Pterodactyl installé sur le nœud, lance un conteneur temporaire avec l'image d'installation déclarée dans l'egg. Pour les jeux Steam, c'est presque toujours une image SteamCMD. Ce conteneur exécute le script d'installation de l'egg, télécharge le jeu, puis s'arrête.

Si une étape échoue, le serveur reste bloqué en installation. Le réflexe à prendre : lire le journal d'installation, et non la console du serveur, qui n'a encore jamais démarré.

2. L'image ghcr.io/parkervcp/steamcmd:debian

Beaucoup d'eggs déclarent l'image ghcr.io/parkervcp/steamcmd:debian. Le projet qui la maintient, yolks, a depuis été transféré sous l'organisation pelican-eggs, et la même image est publiée sous ghcr.io/pelican-eggs/steamcmd:debian.

Nous avons vérifié dans le registre le 2 octobre 2026 : les deux noms pointent vers la même image, avec la même empreinte. Un egg qui utilise encore l'ancien nom fonctionne donc toujours, et vous pouvez passer au nouveau sans urgence, à l'occasion d'une mise à jour de vos eggs.

Si le téléchargement de l'image échoue, le nom n'est donc pas en cause : regardez plutôt la connexion du nœud vers ghcr.io, traitée plus bas. Les autres variantes de l'image (ubuntu, proton, dotnet, sniper) répondent à des besoins précis d'un jeu : n'en changez que si l'egg ou la documentation du jeu le demande.

3. Les codes d'erreur SteamCMD les plus fréquents

SteamCMD termine souvent par une ligne du type Error! App 'XXX' state is 0x202 after update job. Le code hexadécimal indique la cause :

• 0x202 : l'espace disque est insuffisant pour installer ou mettre à jour le jeu.
• 0x402 : les serveurs de mise à jour de Steam sont indisponibles, ou le nœud a un problème de connexion.
• 0x602 : une erreur réseau a interrompu le téléchargement.
• No subscription : le compte utilisé ne possède pas le jeu (voir la section suivante).

Pour 0x402 et 0x602, relancez d'abord l'installation un peu plus tard : les indisponibilités de Steam sont fréquentes et courtes. Si l'erreur revient à chaque tentative, le problème est du côté du nœud.

4. « No subscription » : quand la connexion anonyme ne suffit pas

La plupart des serveurs dédiés se téléchargent avec une connexion anonyme à Steam. Certains exigent un compte qui possède le jeu : SteamCMD refuse alors l'installation avec No subscription.

Renseignez dans ce cas l'identifiant et le mot de passe Steam dans les variables prévues par l'egg, généralement STEAM_USER et STEAM_PASS. Utilisez un compte dédié à cet usage plutôt que votre compte personnel : si Steam Guard est actif, SteamCMD attend un code qu'une installation automatique ne peut pas recevoir.

5. Disque et limites du conteneur d'installation

Un jeu de plusieurs dizaines de gigaoctets ne s'installe pas si la limite de disque du serveur est trop basse, même quand le nœud a de la place. Vérifiez la taille du jeu avant de créer le serveur, et gardez une marge pour les mises à jour, qui téléchargent parfois des fichiers temporaires volumineux.

Côté nœud, Wings applique aussi des limites de mémoire et de processeur au conteneur d'installation, réglées par installer_limits dans /etc/pterodactyl/config.yml. Une installation lourde peut échouer si elles sont trop basses.

df -h /var/lib/pterodactyl

6. Réseau du nœud : DNS et MTU

C'est la cause la plus déroutante, et nous l'avons rencontrée sur l'un de nos propres nœuds : l'installation démarre, puis reste figée, sans message d'erreur clair. L'interface réseau du nœud était en MTU 1450, alors que le réseau Docker de Pterodactyl utilisait 1500. Les gros paquets se perdaient en route, et les téléchargements calaient.

La correction tient en deux réglages : aligner la MTU du réseau Docker de Wings sur celle de l'interface, puis ajouter une règle qui ajuste la taille des segments TCP.

ip link show eth0 | grep -o 'mtu [0-9]*'

# /etc/pterodactyl/config.yml
docker:
  network:
    network_mtu: 1450

iptables -t mangle -A FORWARD -p tcp --tcp-flags SYN,RST SYN -j TCPMSS --clamp-mss-to-pmtu

Vérifiez aussi que le nœud résout ghcr.io et les serveurs de Steam : les serveurs DNS utilisés par les conteneurs se règlent dans docker.network.dns, dans le même fichier.

7. Nœud ARM : SteamCMD n'est pas fait pour

L'image SteamCMD n'est publiée que pour l'architecture amd64 : son manifeste ne contient aucune version ARM. Sur un nœud ARM, qu'il s'agisse d'un Raspberry Pi ou d'un serveur Ampere, l'installation échoue dès le lancement du conteneur. La seule solution fiable est un nœud x86_64.

8. La méthode pour diagnostiquer

Plutôt que de relancer l'installation au hasard, suivez cet ordre :

• Lisez la fin du journal d'installation et repérez l'étape qui échoue : téléchargement de l'image, SteamCMD ou script de l'egg.
• Si c'est SteamCMD, lisez le code d'erreur et reportez-vous à la section 3.
• Vérifiez l'espace disque du nœud et la limite de disque du serveur.
• Testez la connexion du nœud vers ghcr.io et vers Internet.
• Relancez avec la fonction de réinstallation du panel, une fois la cause corrigée.

tail -n 50 /var/log/pterodactyl/install/<identifiant-du-serveur>.log
curl -sI https://ghcr.io | head -n 1

Questions fréquentes

À lire ensuite