Dépannage
Problèmes courants rencontrés en exploitant Saba-chan, avec des procédures de résolution fondées sur le comportement réel du code.

Dépannage
Ce document est organisé selon les symptômes réellement rencontrés par les utilisateurs et explique comment se comporte le code du démon, ainsi que la marche à suivre pour corriger le problème. Les exemples de commandes et les chemins sont donnés pour Windows. Sous Linux, le dossier de données est ~/.config/saba-chan.
1. Le démon ne démarre pas / la GUI ne se connecte pas
1.1 Conflit de port / démon déjà en cours d'exécution
Le démon (saba-core) écoute par défaut sur le port 57474, uniquement sur 127.0.0.1.
- Un seul démon tourne par PC. Si un démon est déjà en cours d'exécution, un démon nouvellement lancé se termine immédiatement, et la GUI et la CLI se connectent à celui qui tourne.
- Si un autre programme occupe le port, le démon réessaie 10 fois à 2 secondes d'intervalle, puis se termine.
# Windows : trouver qui l'utilise
Get-NetTCPConnection -LocalPort 57474 | Select-Object OwningProcess
Get-Process -Id <pid>
- Vous pouvez vérifier si le démon est en vie, sans jeton, sur
http://127.0.0.1:57474/health.saba-chan-cli daemon statusaffiche les mêmes informations. - Si un démon qui ne répond plus est toujours présent, arrêtez-le avec
saba-chan-cli daemon stop. S'il ne disparaît toujours pas, exécutezStop-Process -Name saba-core -Force. - Si vous devez changer de port, modifiez
gui.ipcPortdansconfig.jsonpuis redémarrez. Vous pouvez aussi définir une variable d'environnement commeSABA_IPC_PORT=57480.
1.2 Désaccord de jeton IPC
Le démon crée un nouveau .ipc_token à chaque démarrage. En cas d'échec d'authentification (401), la GUI et la CLI relisent le fichier de jeton et réessaient une fois ; le problème se résout donc généralement de lui-même.
Si « échec de l'authentification » se répète :
- Vérifiez que la GUI et le démon utilisent le même dossier de données. Si vous avez défini
SABA_DATA_DIRouSABA_TOKEN_PATHpour un seul des deux, les emplacements du fichier de jeton diffèrent. - Quittez complètement la GUI et relancez-la.
2. Le démarrage/l'arrêt du serveur se comporte bizarrement
2.1 J'ai cliqué sur Arrêter et rien ne se passe pendant un moment
Cela peut être normal. Le démon procède dans cet ordre :
- Pour les serveurs dotés d'une console, il envoie la
stop_commanddu module à la console (stdin). Pour les jeux sans console, comme Palworld, le module demande au serveur de sauvegarder et de s'arrêter via REST. - Il attend que le serveur s'arrête de lui-même. La valeur par défaut est de 30 secondes ; un module peut la changer avec
[config] stop_timeoutdansmodule.toml, et vous pouvez la régler par serveur avec le délai d'arrêt de l'onglet Saba-chan de l'écran du serveur. Augmentez-la si le monde est volumineux et que la sauvegarde prend du temps. - S'il est toujours en vie, il est tué de force.
- Pendant 30 secondes après l'arrêt, la détection des crashs est suspendue.
S'il finit toujours par être tué de force, c'est que le serveur ne reçoit pas la commande d'arrêt. Vérifiez si la commande d'arrêt apparaît dans la console du serveur. Exemples : stop pour Minecraft, quit pour Zomboid.
2.2 Le serveur ne cesse de redémarrer
Lorsqu'un serveur s'arrête, le démon classe la cause en arrêté par vous / arrêté en jeu / crash / inconnu. Par défaut, le redémarrage automatique n'a lieu que pour les crashs ; l'attente commence à 5 secondes et double à chaque fois, et Saba-chan ne redémarre plus le serveur au-delà de 3 redémarrages en 10 minutes.
Résolution :
- Vérifiez la classification sous « Arrêts récents » dans l'écran du serveur.
- Pour arrêter les redémarrages, désactivez « Redémarrer après un crash » sous « Redémarrage auto » dans l'onglet Saba-chan de l'écran du serveur. Si vous avez activé « Redémarrer aussi sur les arrêts inconnus », vérifiez-le également.
- Consultez les logs de console du serveur (
instances\<id>\logs\) pour trouver la cause du crash. Pour un OOM Java (OutOfMemoryError), augmentez le paramètre de mémoire.
2.3 Erreur « conflit de port » au démarrage
La vérification de pré-démarrage a constaté que le port du serveur est utilisé par une autre instance en cours d'exécution ou par un autre programme. En général, un processus précédent traîne encore, ou un autre serveur de jeu utilise le même port.
- Trouvez le processus qui utilise ce port et arrêtez-le.
- Si ce n'est pas possible, changez le port dans les paramètres de l'instance et redémarrez.
- Vous pouvez désactiver la vérification elle-même avec « Détection de conflit de port » dans les paramètres de la GUI (
gui.portConflictCheck), mais ce n'est pas recommandé.
2.4 « Accord requis » (EULA de Minecraft, etc.)
Pour les jeux dont le module déclare des conditions (p. ex. l'EULA de Minecraft), vous devez les lire et les accepter avant que le serveur puisse démarrer. Tant que ce n'est pas fait, le démarrage est bloqué avec agreement_required.
- Lorsque vous démarrez le serveur dans la GUI, lisez les conditions dans la boîte de dialogue qui apparaît, cochez la case et démarrez-le.
- Vous ne pouvez pas accepter les conditions depuis Discord. Une fois que vous les avez acceptées dans Saba-chan sur votre PC, vous pouvez aussi démarrer le serveur depuis Discord.
2.5 L'enregistrement des paramètres du serveur est rejeté
unknown_setting: La clé n'est ni un champ d'instance commun ni un paramètre déclaré par le module. Il s'agit d'une faute de frappe ou d'un paramètre d'un autre jeu.validation_failed/invalid_format: La plage ou le format de la valeur ne correspond pas à la déclaration du module. Corrigez le champ indiqué dans l'erreur.- « Paramètres enregistrés, mais le fichier de configuration du jeu n'a pas pu être mis à jour » : Les paramètres ont été enregistrés, mais le module n'a pas pu modifier le fichier de configuration du jeu. Assurez-vous que le fichier du jeu n'est pas verrouillé par un autre programme et enregistrez de nouveau.
2.6 Un composant non vérifié refuse de s'exécuter
Les modules et extensions qui n'ont pas été installés depuis le catalogue officiel, ou dont les fichiers ont changé depuis, sont marqués « non vérifiés ». Saba-chan ne les analyse pas avec un antivirus. Ils s'exécutent dans un environnement isolé (AppContainer sous Windows, bubblewrap sous Linux) ; là où l'isolation est impossible (Linux sans bubblewrap ou avec un bubblewrap inutilisable, macOS), ils ne s'exécutent qu'après votre consentement pour leurs fichiers actuels. Si l'exécution est bloquée, l'un de ces codes est affiché.
| Code | Signification | Correction |
|---|---|---|
launch_outside_instance | Le module a tenté d'exécuter un programme en dehors du dossier du serveur | Vérifiez la provenance du module |
sandbox_unavailable | L'environnement isolé n'a pas pu être préparé sur ce PC | Voir ci-dessous |
En cas de sandbox_unavailable, la GUI demande « Exécuter sans isolation ? ». N'autorisez cela que pour des composants de confiance. Si vous l'autorisez, ce composant peut accéder à tous les fichiers et au réseau avec les permissions de votre compte. Le consentement ne peut être donné que sur ce PC, et il est redemandé si les fichiers du composant changent. Vous pouvez retirer votre consentement dans Paramètres → Sécurité → « Exécuter sans isolation ».
La solution la plus sûre consiste à réinstaller le module ou l'extension depuis le catalogue officiel. Les composants vérifiés sont dispensés de ces contrôles.
3. Problèmes d'installation / de mise à jour
3.1 L'installation échoue en cours de route
- Lorsque l'installateur s'arrête, l'écran d'erreur affiche un code de cause (
fetch_failed,download_failed,extract_failed,elevation_failed,installer_outdated) et le chemin du log. Le log est écrit dans%TEMP%\saba-chan-installer.log. installer_outdatedsignifie que l'installateur est plus ancien que la dernière version. Téléchargez et lancez le dernier installateur.- Pour les problèmes réseau, vérifiez votre connexion, puis cliquez sur Réessayer ou relancez l'installateur.
- Un échec lors de la préparation du runtime Python n'interrompt pas l'installation. Le démon le prépare de nouveau au premier lancement, et relancer l'installateur supprime un runtime endommagé et le retélécharge.
3.2 La progression de l'installation du serveur ne s'affiche pas ou reste bloquée (pour les développeurs de modules)
La progression de l'installation du serveur est disponible sur GET /api/provision-progress/:name.
- Vérifiez que le module/l'extension écrit sa progression sur stderr au format
PROGRESS:{json}. - Vérifiez que le JSON est valide (échappez les guillemets doubles et les sauts de ligne dans
message). - Une progression réussie est supprimée 5 secondes après la fin ; un polling trop tardif la trouvera donc déjà vide. Une progression en échec reste jusqu'à ce que l'utilisateur la ferme, et s'il s'agissait d'un serveur nouvellement créé, la fermer supprime cette instance.
3.3 Une mise à jour ne s'applique pas
Les mises à jour sont vérifiées par rapport aux informations de version signées fournies par le relais Saba-chan, et le hachage de chaque fichier est vérifié avant l'application. Si la signature ou un hachage ne correspond pas, rien n'est appliqué.
- Si, après une mise à jour, vous voyez un avis indiquant que certains éléments n'ont pas pu être mis à jour, cliquez dessus pour voir lesquels ont échoué.
- Vérifiez de nouveau les mises à jour dans les paramètres de la GUI et appliquez-les.
- Les mises à jour qui remplacent le démon, la GUI ou l'installateur lui-même sont appliquées par l'installateur (
saba-chan-installer) après l'arrêt du démon. Ne relancez pas Saba-chan pendant l'application. - Si cela ne suffit toujours pas, quittez Saba-chan, videz le dossier
updates\et réessayez.
4. Bot Discord / appairage cloud
4.1 Le bot ne répond pas
- Écrivez le préfixe (par défaut
Saba-chan), une espace, puis le nom du serveur et la commande. Exemple :Saba-chan minecraft status. - L'appairage doit avoir été effectué dans la GUI pour que
.node_tokensoit enregistré. - Saba-chan (le démon) doit être en cours d'exécution. Le bot tourne dans le cloud, mais les commandes sont exécutées par le démon sur ce PC.
- Si le démon ne parvient pas à se connecter au relais, consultez les avertissements récents dans Paramètres → Dépannage → « Diagnostic » de la GUI. Si vous voyez « older than relay minimum », mettez à jour Saba-chan.
- Assurez-vous que le bot officiel est invité sur votre serveur Discord et qu'il n'est pas en veille. Si c'est le cas, réveillez-le avec
/saba wake.
4.2 Le code d'appairage est « expiré »
Un code d'appairage n'est valable que 5 minutes. Générez un nouveau code depuis la GUI.
4.3 Connexion au relais rejetée avec un 401
| Erreur | Cause | Correction |
|---|---|---|
TOKEN_REPLACED | Lors d'un appairage ailleurs, ce PC a été choisi avec Reconnecter, ce qui a remplacé son jeton | Appairez de nouveau si vous voulez continuer à utiliser ce PC |
INVALID_TOKEN / NODE_NOT_FOUND | .node_token est incorrect ou a été supprimé côté serveur | Appairez de nouveau (cela invalide le jeton existant) |
MISSING_TOKEN / INVALID_TOKEN_FORMAT | Le fichier de jeton est absent ou mal formé | Appairez de nouveau |
4.4 Les commandes musicales ne fonctionnent pas
- Dans la page Discord de la GUI, vérifiez que la musique est activée dans les paramètres de ce serveur Discord.
- La personne qui lance la commande doit déjà se trouver dans un salon vocal Discord. Si le bot ne peut pas rejoindre le salon vocal, vérifiez les permissions du bot sur ce salon.
- La lecture est assurée par le serveur de musique officiel ; vous n'avez donc pas besoin de ffmpeg ni de yt-dlp sur votre PC.
4.5 Impossible de se connecter à un daemon distant
| Message | Que faire |
|---|---|
Ce PC n'est pas ouvert aux connexions distantes | Sur le PC serveur, Autoriser les connexions distantes est désactivé dans Paramètres → Connexion → Daemon distant. Activez-le et enregistrez |
Impossible de joindre le démon distant | Vérifiez que le PC serveur et son Saba-chan sont allumés et en ligne. S'il n'est pas joignable directement, la connexion passe par le cloud Saba-chan, la redirection de port n'est donc pas obligatoire |
Ce PC n'est pas connecté à Discord | Appairez les deux PC avec le même compte Discord |
Le daemon distant n'accepte plus ce PC | Le PC serveur l'a déconnecté. Appuyez de nouveau sur Connecter sur votre PC |
Le port est déjà utilisé | Un autre programme utilise le même port. Changez de port |
Cela ne peut se faire que sur ce PC | Les mises à jour ou le démarrage à la connexion, par exemple, ne se font pas à distance |
4.6 Un lien Saba-chan web ne s'ouvre pas
- Un lien ne s'ouvre qu'une fois, dans les 5 minutes. Demandez-en un nouveau avec
/saba web. - Si vous voyez
Impossible de joindre votre PC, vérifiez que Saba-chan tourne sur le PC et qu'il est à jour. - Sur un lien ouvert sans PC, les menus Serveurs, Modules et PC sont verrouillés. Installez l'application, faites
/saba connect, puis demandez un nouveau lien. - Fermer l'onglet ou recharger termine la session. C'est normal.
5. Récupération des données / de la configuration
5.1 config.json est corrompu
- Le démon met de côté un
config.jsoncorrompu sousconfig.json.corrupt-<horodatage>et restaure automatiquement à partir deconfig.json.bak(la dernière copie valide). - Si
.bakest lui aussi absent ou corrompu, le démon démarre avec les valeurs par défaut. Tous les paramètres, y compris ceux de l'intégration Discord, sont réinitialisés ; ressaisissez donc les valeurs nécessaires dans la GUI en vous appuyant sur le fichier.corrupt-mis de côté. - La liste des serveurs (
instances\) et.node_tokensont distincts deconfig.json; ils sont donc conservés.
5.2 Réinitialisation complète
1. Quittez la GUI, la CLI et le démon de Saba-chan
2. Sauvegardez puis supprimez tout le dossier %APPDATA%\saba-chan
3. Lancez Saba-chan → il se reconstruit avec les valeurs par défaut
Attention : si vous avez installé des serveurs à l'emplacement par défaut, les fichiers des serveurs de jeu et les sauvegardes se trouvent dans %APPDATA%\saba-chan\instances\ et sont supprimés avec lui. Les fichiers de jeu ne survivent que si vous avez choisi un dossier de serveur en dehors de ce dossier.
6. Où trouver les logs ?
| Emplacement | Contenu |
|---|---|
%APPDATA%\saba-chan\logs\saba-chan-*.log | Log de la GUI. Contient aussi la sortie d'un démon lancé par la GUI |
| Fenêtre de console du démon dans la GUI | Log du démon (tampon en mémoire, 10 000 dernières lignes) |
| GUI Paramètres → Dépannage → Diagnostic | État du démon et avertissements/erreurs récents. Ne contient ni mots de passe ni jetons |
%APPDATA%\saba-chan\instances\<id>\logs\ | Logs de console du serveur (console.log, sessions\) |
| Onglet Console de la GUI | Sortie du serveur de jeu par instance |
%APPDATA%\saba-chan\audit.log | Historique des démarrages/arrêts/commandes des serveurs (avec la source, secrets masqués) |
%TEMP%\saba-chan-installer.log | Log de l'installateur |
Vous pouvez modifier le niveau de log du démon avec la variable d'environnement RUST_LOG lorsque vous lancez le démon directement (par défaut info).
7. Liste de vérification pour signaler un problème
Avant d'ouvrir un nouveau ticket, vérifiez et joignez les éléments suivants.
- La version de Saba-chan (
saba-chan-cli version, ou le Diagnostic de la GUI). - Les étapes de reproduction.
- Les logs pertinents (extraits découpés par horodatage). La sortie de « Copier » dans le Diagnostic de la GUI aide aussi.
- L'OS / la build (p. ex. Windows 10 x64 21H2).
- Ne joignez jamais les fichiers de jeton (
.ipc_token,.node_token) ni leur contenu.
Dépôts :
- Principal : github.com/WareAoba/saba-chan/issues
- Modules : github.com/WareAoba/saba-chan-modules/issues
- Extensions : github.com/WareAoba/saba-chan-extensions/issues