Fehlerbehebung
Häufige Probleme beim Betrieb von Saba-chan mit Lösungsschritten, die auf dem tatsächlichen Verhalten des Codes beruhen.

Fehlerbehebung
Dieses Dokument ist nach den Symptomen geordnet, die Benutzer tatsächlich erleben, und erklärt, wie sich der Daemon-Code verhält, sowie die Schritte zur Behebung. Befehlsbeispiele und Pfade gelten für Windows. Unter Linux ist der Datenordner ~/.config/saba-chan.
1. Daemon startet nicht / GUI kann sich nicht verbinden
1.1 Portkonflikt / Daemon läuft bereits
Der Daemon (saba-core) lauscht standardmäßig auf Port 57474, und zwar nur auf 127.0.0.1.
- Pro PC läuft nur ein Daemon. Läuft bereits ein Daemon, beendet sich ein neu gestarteter sofort, und GUI und CLI verbinden sich mit dem laufenden.
- Belegt ein anderes Programm den Port, versucht der Daemon es 10-mal im Abstand von 2 Sekunden erneut und beendet sich dann.
# Windows: herausfinden, wer den Port belegt
Get-NetTCPConnection -LocalPort 57474 | Select-Object OwningProcess
Get-Process -Id <pid>
- Ob der Daemon lebt, können Sie ohne Token unter
http://127.0.0.1:57474/healthprüfen.saba-chan-cli daemon statuszeigt dieselben Informationen. - Hängt noch ein nicht reagierender Daemon herum, stoppen Sie ihn mit
saba-chan-cli daemon stop. Verschwindet er dann immer noch nicht, führen SieStop-Process -Name saba-core -Forceaus. - Müssen Sie den Port ändern, bearbeiten Sie
gui.ipcPortinconfig.jsonund starten neu. Oder setzen Sie eine Umgebungsvariable wieSABA_IPC_PORT=57480.
1.2 IPC-Token stimmt nicht überein
Der Daemon erzeugt bei jedem Start ein neues .ipc_token. Schlägt die Authentifizierung fehl (401), lesen GUI und CLI die Token-Datei erneut ein und versuchen es noch einmal; meist erledigt sich das also von selbst.
Wenn „Authentifizierung fehlgeschlagen“ immer wieder auftritt:
- Prüfen Sie, dass GUI und Daemon denselben Datenordner verwenden. Haben Sie
SABA_DATA_DIRoderSABA_TOKEN_PATHnur für einen von beiden gesetzt, liegen die Token-Dateien an unterschiedlichen Orten. - Beenden Sie die GUI vollständig und starten Sie sie erneut.
2. Starten/Stoppen von Servern verhält sich seltsam
2.1 Ich habe auf Stoppen geklickt, und eine Weile passiert nichts
Das kann normal sein. Der Daemon geht in dieser Reihenfolge vor:
- Bei Servern mit Konsole sendet er den
stop_commanddes Moduls an die Konsole (stdin). Bei Spielen ohne Konsole, etwa Palworld, fordert das Modul den Server über REST auf, zu speichern und herunterzufahren. - Er wartet, bis sich der Server von selbst beendet. Standard sind 30 Sekunden; ein Modul kann das mit
[config] stop_timeoutinmodule.tomländern, und Sie können es pro Server im Tab Saba-chan der Serveransicht über die Stopp-Wartezeit ändern. Dauert das Speichern bei einer großen Welt lange, erhöhen Sie den Wert. - Läuft der Server dann noch, wird er zwangsweise beendet.
- Für 30 Sekunden nach dem Stoppen wird die Absturzerkennung unterdrückt.
Wird der Server jedes Mal zwangsweise beendet, kommt der Stoppbefehl nicht an. Prüfen Sie, ob der Stoppbefehl in der Serverkonsole erscheint. Beispiele: Minecraft stop, Zomboid quit.
2.2 Der Server startet immer wieder neu
Wenn ein Server beendet wird, ordnet der Daemon die Ursache als von Ihnen gestoppt / im Spiel gestoppt / Absturz / unbekannt ein. Standardmäßig erfolgt der automatische Neustart nur bei Abstürzen; die Wartezeit beginnt bei 5 Sekunden und verdoppelt sich jedes Mal, und nach mehr als 3 Neustarts innerhalb von 10 Minuten startet er nicht mehr neu.
Lösung:
- Prüfen Sie die Einstufung unter „Letzte Beendigungen“ im Serverbildschirm.
- Um die Neustarts zu unterbinden, schalten Sie im Tab Saba-chan der Serveransicht unter „Automatischer Neustart“ die Option „Nach einem Absturz neu starten“ aus. Haben Sie „Auch bei unbekanntem Beenden neu starten“ aktiviert, prüfen Sie auch diese Option.
- Suchen Sie in den Serverkonsolen-Protokollen (
instances\<id>\logs\) nach der Absturzursache. Bei einem Java-OOM (OutOfMemoryError) erhöhen Sie die Speichereinstellung.
2.3 Fehler „Portkonflikt“ beim Starten
Die Prüfung vor dem Start hat festgestellt, dass der Port des Servers von einer anderen laufenden Instanz oder einem anderen Programm belegt ist. Meist hängt noch ein früherer Prozess herum, oder ein anderer Spieleserver nutzt denselben Port.
- Finden Sie den Prozess, der den Port belegt, und stoppen Sie ihn.
- Ist das nicht möglich, ändern Sie den Port in den Instanzeinstellungen und starten Sie erneut.
- Sie können die Prüfung selbst mit „Portkonflikterkennung“ in den GUI-Einstellungen (
gui.portConflictCheck) abschalten, das wird aber nicht empfohlen.
2.4 „Zustimmung erforderlich“ (Minecraft EULA usw.)
Bei Spielen, deren Modul Bedingungen deklariert (z. B. die Minecraft EULA), müssen Sie diese lesen und ihnen zustimmen, bevor der Server starten kann. Bis dahin wird der Start mit agreement_required blockiert.
- Wenn Sie den Server in der GUI starten, lesen Sie die Bedingungen im erscheinenden Dialog, aktivieren Sie das Kontrollkästchen und starten Sie ihn.
- Über Discord können Sie Bedingungen nicht zustimmen. Sobald Sie in Saba-chan auf Ihrem PC zugestimmt haben, können Sie den Server auch aus Discord starten.
2.5 Speichern von Servereinstellungen wird abgelehnt
unknown_setting: Der Schlüssel ist weder ein allgemeines Instanzfeld noch eine vom Modul deklarierte Einstellung. Es handelt sich um einen Tippfehler oder eine Einstellung eines anderen Spiels.validation_failed/invalid_format: Bereich oder Format des Werts entspricht nicht der Deklaration des Moduls. Korrigieren Sie das in der Fehlermeldung genannte Feld.- „Die Einstellungen wurden gespeichert, aber die Konfigurationsdatei des Spiels konnte nicht aktualisiert werden“: Die Einstellungen wurden gespeichert, aber das Modul konnte die Konfigurationsdatei des Spiels nicht bearbeiten. Stellen Sie sicher, dass die Spieldatei nicht von einem anderen Programm gesperrt ist, und speichern Sie erneut.
2.6 Eine nicht verifizierte Komponente lässt sich nicht ausführen
Module und Erweiterungen, die nicht aus dem offiziellen Katalog installiert wurden oder deren Dateien sich danach geändert haben, werden als „nicht verifiziert“ markiert. Saba-chan scannt sie nicht mit einem Virenschutz. Unter Windows laufen sie in einer isolierten Umgebung (AppContainer), unter Linux mit bubblewrap; in Umgebungen, die sich nicht isolieren lassen (Linux ohne oder mit nicht nutzbarem bubblewrap, macOS), laufen sie erst, nachdem du ihren aktuellen Dateien zugestimmt hast. Ist die Ausführung blockiert, wird einer dieser Codes angezeigt.
| Code | Bedeutung | Lösung |
|---|---|---|
launch_outside_instance | Das Modul hat versucht, ein Programm außerhalb des Serverordners auszuführen | Prüfen Sie, woher das Modul stammt |
sandbox_unavailable | Die isolierte Umgebung konnte auf diesem PC nicht vorbereitet werden | Siehe unten |
Bei sandbox_unavailable fragt die GUI „Ohne Isolation ausführen?“. Erlauben Sie das nur für Komponenten, denen Sie vertrauen. Wenn Sie es erlauben, kann diese Komponente mit den Rechten Ihres Kontos auf alle Dateien und das Netzwerk zugreifen. Die Zustimmung kann nur auf diesem PC erteilt werden, und Sie werden erneut gefragt, wenn sich die Dateien der Komponente ändern. Sie können die Zustimmung unter Einstellungen → Sicherheit → „Ohne Isolation ausführen“ widerrufen.
Die zuverlässigste Lösung ist, das Modul oder die Erweiterung aus dem offiziellen Katalog neu zu installieren. Verifizierte Komponenten überspringen diese Prüfungen.
3. Probleme bei Installation / Update
3.1 Die Installation bricht mittendrin ab
- Wenn das Installationsprogramm anhält, zeigt der Fehlerbildschirm einen Ursachencode (
fetch_failed,download_failed,extract_failed,elevation_failed,installer_outdated) und den Protokollpfad. Das Protokoll wird nach%TEMP%\saba-chan-installer.loggeschrieben. installer_outdatedbedeutet, dass das Installationsprogramm älter als das neueste Release ist. Laden Sie das neueste Installationsprogramm herunter und führen Sie es aus.- Bei Netzwerkproblemen prüfen Sie Ihre Verbindung und klicken dann auf Erneut versuchen oder führen das Installationsprogramm erneut aus.
- Ein Fehler beim Vorbereiten der Python-Laufzeit hält die Installation nicht an. Der Daemon bereitet sie beim ersten Start erneut vor, und ein erneutes Ausführen des Installationsprogramms löscht eine beschädigte Laufzeit und lädt sie neu herunter.
3.2 Der Fortschritt der Serverinstallation wird nicht angezeigt oder hängt (für Modulentwickler)
Der Fortschritt der Serverinstallation ist unter GET /api/provision-progress/:name verfügbar.
- Prüfen Sie, dass das Modul bzw. die Erweiterung den Fortschritt im Format
PROGRESS:{json}nach stderr ausgibt. - Prüfen Sie, dass das JSON gültig ist (doppelte Anführungszeichen und Zeilenumbrüche in
messagemaskieren). - Erfolgreicher Fortschritt wird 5 Sekunden nach Abschluss entfernt; wer zu spät abfragt, findet ihn bereits leer vor. Fehlgeschlagener Fortschritt bleibt bestehen, bis der Benutzer ihn schließt, und handelte es sich um einen neu erstellten Server, wird diese Instanz beim Schließen gelöscht.
3.3 Ein Update wird nicht angewendet
Updates werden anhand signierter Release-Informationen geprüft, die das Saba-chan-Relay bereitstellt, und vor dem Anwenden wird der Hash jeder Datei verifiziert. Stimmt die Signatur oder ein Hash nicht, wird nichts angewendet.
- Sehen Sie nach einem Update einen Hinweis, dass einige Elemente nicht aktualisiert werden konnten, klicken Sie darauf, um zu sehen, welche fehlgeschlagen sind.
- Suchen Sie in den GUI-Einstellungen erneut nach Updates und wenden Sie sie an.
- Updates, die den Daemon, die GUI oder den Installer selbst ersetzen, wendet der Installer (
saba-chan-installer) an, nachdem sich der Daemon beendet hat. Starten Sie Saba-chan währenddessen nicht neu. - Hilft das immer noch nicht, beenden Sie Saba-chan, leeren Sie den Ordner
updates\und versuchen Sie es erneut.
4. Discord-Bot / Cloud-Pairing
4.1 Der Bot reagiert nicht
- Schreiben Sie das Präfix (Standard
Saba-chan), ein Leerzeichen, dann den Servernamen und den Befehl. Beispiel:Saba-chan minecraft status. - Das Pairing muss in der GUI abgeschlossen sein, sodass
.node_tokengespeichert ist. - Saba-chan (der Daemon) muss laufen. Der Bot läuft in der Cloud, aber die Befehle führt der Daemon auf diesem PC aus.
- Kann sich der Daemon nicht mit dem Relay verbinden, prüfen Sie die letzten Warnungen in der GUI unter Einstellungen → Fehlerbehebung → „Diagnose“. Sehen Sie „older than relay minimum“, aktualisieren Sie Saba-chan.
- Stellen Sie sicher, dass der offizielle Bot in Ihren Discord-Server eingeladen ist und nicht schläft. Falls doch, wecken Sie ihn mit
/saba wake.
4.2 Pairing-Code ist „abgelaufen“
Ein Pairing-Code ist nur 5 Minuten gültig. Erzeugen Sie in der GUI einen neuen Code.
4.3 Relay-Verbindung mit 401 abgelehnt
| Fehler | Ursache | Lösung |
|---|---|---|
TOKEN_REPLACED | Beim Pairing an anderer Stelle wurde dieser PC mit Neu verbinden gewählt und sein Token ersetzt | Pairen Sie erneut, wenn Sie diesen PC weiter nutzen möchten |
INVALID_TOKEN / NODE_NOT_FOUND | .node_token ist falsch oder wurde auf dem Server entfernt | Erneut pairen (macht das bestehende Token ungültig) |
MISSING_TOKEN / INVALID_TOKEN_FORMAT | Die Token-Datei fehlt oder ist fehlerhaft | Erneut pairen |
4.4 Musikbefehle funktionieren nicht
- Prüfen Sie auf der Discord-Seite der GUI, ob Musik in den Einstellungen dieses Discord-Servers aktiviert ist.
- Die Person, die den Befehl gibt, muss sich bereits in einem Discord-Sprachkanal befinden. Kann der Bot dem Sprachkanal nicht beitreten, prüfen Sie seine Kanalberechtigungen.
- Die Wiedergabe übernimmt der offizielle Musikserver; Sie brauchen daher weder ffmpeg noch yt-dlp auf Ihrem PC.
4.5 Keine Verbindung zum Remote-Daemon
| Meldung | Was zu tun ist |
|---|---|
Dieser PC ist nicht für Remote-Verbindungen geöffnet | Schalten Sie auf dem Server-PC unter Einstellungen → Verbindung → Remote-Daemon Remote-Verbindungen erlauben ist ausgeschaltet. Schalten Sie es ein und speichern Sie |
Der Remote-Daemon war nicht erreichbar | Prüfen Sie, ob der Server-PC und sein Saba-chan laufen und online sind. Ist er nicht direkt erreichbar, läuft die Verbindung über die Saba-chan-Cloud, eine Portweiterleitung ist also nicht nötig |
Dieser PC ist nicht mit Discord verbunden | Koppeln Sie beide PCs mit demselben Discord-Konto |
Der Remote-Daemon akzeptiert diesen PC nicht mehr | Der Server-PC hat ihn getrennt. Klicken Sie auf Ihrem PC erneut auf Verbinden |
Der Port wird bereits verwendet | Ein anderes Programm nutzt denselben Port. Ändern Sie den Port |
Das geht nur direkt auf diesem PC | Dinge wie Updates und der Start beim Anmelden gehen nicht aus der Ferne |
4.6 Ein Saba-chan-Web-Link öffnet sich nicht
- Ein Link öffnet sich nur einmal und nur innerhalb von 5 Minuten. Holen Sie mit
/saba webeinen neuen. - Erscheint
Dein PC war nicht erreichbar, prüfen Sie, ob Saba-chan auf dem PC läuft und aktuell ist. - In einem Link, der ohne PC geöffnet wurde, sind die Menüs für Server, Module und PCs gesperrt. Installieren Sie die App, führen Sie
/saba connectaus und holen Sie dann einen neuen Link. - Tab schließen oder neu laden beendet die Sitzung. Das ist so vorgesehen.
5. Wiederherstellung von Daten / Konfiguration
5.1 config.json ist beschädigt
- Der Daemon verschiebt eine beschädigte
config.jsonalsconfig.json.corrupt-<timestamp>beiseite und stellt automatisch ausconfig.json.bak(der letzten funktionierenden Kopie) wieder her. - Fehlt auch
.bakoder ist sie beschädigt, startet er mit Standardwerten. Alle Einstellungen einschließlich Ihrer Discord-Anbindung werden zurückgesetzt; geben Sie die benötigten Werte daher in der GUI erneut ein und nutzen Sie die verschobene.corrupt--Datei als Referenz. - Die Serverliste (
instances\) und.node_tokensind vonconfig.jsongetrennt und bleiben daher erhalten.
5.2 Vollständiges Zurücksetzen
1. Saba-chan-GUI, CLI und Daemon beenden
2. Den gesamten Ordner %APPDATA%\saba-chan sichern und löschen
3. Saba-chan starten → es wird mit Standardwerten neu aufgebaut
Achtung: Haben Sie Server am Standardort installiert, liegen Spieleserver-Dateien und Backups in %APPDATA%\saba-chan\instances\ und werden mitgelöscht. Spieldateien bleiben nur erhalten, wenn Sie einen Serverordner außerhalb dieses Ordners gewählt haben.
6. Wo finde ich die Protokolle?
| Ort | Inhalt |
|---|---|
%APPDATA%\saba-chan\logs\saba-chan-*.log | GUI-Protokoll. Enthält auch die Ausgabe eines von der GUI gestarteten Daemons |
| Daemon-Konsolenfenster der GUI | Daemon-Protokoll (Puffer im Speicher, letzte 10.000 Zeilen) |
| GUI-Einstellungen → Fehlerbehebung → Diagnose | Daemon-Status und letzte Warnungen/Fehler. Enthält keine Passwörter oder Tokens |
%APPDATA%\saba-chan\instances\<id>\logs\ | Serverkonsolen-Protokolle (console.log, sessions\) |
| Tab „Konsole“ der GUI | Spieleserver-Ausgabe pro Instanz |
%APPDATA%\saba-chan\audit.log | Aufzeichnung von Serverstart/-stopp/-befehlen (mit Quelle, Geheimnisse maskiert) |
%TEMP%\saba-chan-installer.log | Protokoll des Installationsprogramms |
Die Protokollstufe des Daemons können Sie mit der Umgebungsvariable RUST_LOG ändern, wenn Sie den Daemon direkt ausführen (Standard info).
7. Checkliste für Fehlerberichte
Bevor Sie ein neues Issue eröffnen, prüfen Sie bitte Folgendes und hängen Sie es an.
- Saba-chan-Version (
saba-chan-cli versionoder GUI-Diagnose). - Schritte zur Reproduktion.
- Relevante Protokolle (nach Zeitstempel gekürzte Auszüge). Auch die Ausgabe von „Kopieren“ in der GUI-Diagnose hilft.
- Betriebssystem / Build (z. B. Windows 10 x64 21H2).
- Hängen Sie niemals die Token-Dateien (
.ipc_token,.node_token) oder deren Inhalt an.
Repositories:
- Haupt-Repository: github.com/WareAoba/saba-chan/issues
- Module: github.com/WareAoba/saba-chan-modules/issues
- Erweiterungen: github.com/WareAoba/saba-chan-extensions/issues