Troubleshooting

This document organizes things by the symptoms users actually experience and explains how the daemon code behaves plus the steps to fix it. Saba-chan currently supports Windows only.

1. Daemon Won't Start / GUI Can't Connect

1.1 Port conflict / daemon already running

The daemon (saba-core) listens on port 57474 by default, on 127.0.0.1 only.

• Only one daemon runs per PC. If a daemon is already running, a newly launched one exits right away, and the GUI and CLI connect to the running one.
• If another program holds the port, the daemon retries 10 times at 2-second intervals and then exits.

# Windows: see who's using it
Get-NetTCPConnection -LocalPort 57474 | Select-Object OwningProcess
Get-Process -Id <pid>

• You can check whether the daemon is alive without a token at http://127.0.0.1:57474/health. saba-chan-cli daemon status shows the same information.
• If an unresponsive daemon is still around, stop it with saba-chan-cli daemon stop. If it still won't go away, run Stop-Process -Name saba-core -Force.
• If you need to change the port, edit gui.ipcPort in config.json and restart. Or set an environment variable such as SABA_IPC_PORT=57480.

1.2 IPC token mismatch

The daemon creates a new .ipc_token every time it starts. When authentication fails (401), the GUI and CLI re-read the token file and retry once, so this usually fixes itself.

If "authentication failed" keeps repeating:

• Check that the GUI and the daemon look at the same data folder. If you set SABA_DATA_DIR or SABA_TOKEN_PATH for only one of them, the token file locations differ.
• Quit the GUI completely and launch it again.

2. Server Start/Stop Behaves Strangely

2.1 I clicked Stop and nothing happens for a while

That can be normal. The daemon's policy is:

1. For servers with a console, it sends the module's stop_command to the console (stdin). For games without a console, such as Palworld, the module asks the server to save and shut down over REST.
2. It waits for the server to exit on its own. The default is 30 seconds; a module can change it with [config] stop_timeout in module.toml.
3. If it's still alive, it is force-killed.
4. For 30 seconds after stopping, crash detection is suppressed.

If it always ends up being force-killed, the server isn't receiving the stop command. Check whether the stop command shows up in the server console. Examples: Minecraft stop, Zomboid quit.

2.2 Server keeps coming back up

When a server exits, the daemon classifies the cause as stopped by you / stopped in-game / crash / unknown. By default, auto restart happens only for crashes; the wait starts at 5 seconds and doubles each time, and it gives up after more than 3 restarts within 10 minutes.

Resolution:

• Check the classification under "Recent exits" on the server screen.
• To stop restarts, turn off "Restart after a crash" under "Auto restart" in the server settings. If you turned on "Also restart on unknown exits", check that too.
• Check the server console logs (instances\<id>\logs\) for the crash cause. For a Java OOM (OutOfMemoryError), increase the memory setting.

2.3 "Port conflict" error when starting

The pre-start check found that the server's port is in use by another running instance or another program. Usually a previous process is still around, or another game server is using the same port.

• Find the process using that port and stop it.
• If that's not possible, change the port in the instance settings and start again.
• You can turn the check itself off with "Port Conflict Detection" in the GUI settings (gui.portConflictCheck), but it's not recommended.

2.4 "Agreement required" (Minecraft EULA, etc.)

For games whose module declares terms (e.g., the Minecraft EULA), you must read and accept them before the server can start. Until you do, starting is blocked with agreement_required.

• When you start the server in the GUI, read the terms in the dialog that appears, check the box, and start it.
• You can't accept terms from Discord. Once you accept them in Saba-chan on your PC, you can start the server from Discord as well.

2.5 Saving server settings is rejected

• unknown_setting — The key is neither a common instance field nor a setting the module declares. It's a typo or a setting from another game.
• validation_failed / invalid_format — The value's range or format doesn't match the module's declaration. Fix the field shown in the error.
• "Settings were saved, but the game's config file couldn't be updated" — The settings were saved, but the module couldn't edit the game's config file. Make sure the game file isn't locked by another program and save again.

2.6 An unverified component won't run

Modules and extensions that weren't installed from the official catalog, or whose files changed afterward, are marked "unverified". On Windows they are scanned with antivirus (Microsoft Defender / AMSI) before running and then run in an isolated environment (AppContainer). If running is blocked, one of these codes is shown.

On sandbox_unavailable, the GUI asks "Run without isolation?". Allow it only for components you trust. If you allow it, that component can access every file and the network with your account's permissions. Consent can only be given on this PC, and you are asked again if the component's files change. You can withdraw consent under Settings → Advanced → "Run without isolation".

The surest fix is to reinstall the module or extension from the official catalog. Verified components skip these checks.

3. Installation / Update Issues

3.1 Installation fails midway

• When the installer stops, the error screen shows a cause code (fetch_failed, download_failed, extract_failed, elevation_failed, installer_outdated) and the log path. The log is written to %TEMP%\saba-chan-installer.log.
• installer_outdated means the installer is older than the latest release. Download and run the latest installer.
• For network problems, check your connection, then click Retry or run the installer again.
• A failure while preparing the Python runtime doesn't stop the installation. The daemon prepares it again on first launch, and re-running the installer deletes a damaged runtime and downloads it fresh.

3.2 Server install progress doesn't show or is stuck (for module developers)

Server install progress is available at GET /api/provision-progress/:name.

• Verify that the module/extension prints progress to stderr in the PROGRESS:{json} format.
• Verify the JSON is valid (escape double quotes and newlines inside message).
• Successful progress is removed 5 seconds after completion, so polling too late will see it already empty. Failed progress stays until the user dismisses it, and if it was a newly created server, dismissing it deletes that instance.

3.3 An update isn't applied

Updates are checked against signed release information provided by the Saba-chan relay, and every file's hash is verified before applying. If the signature or a hash doesn't match, nothing is applied.

• If you see a notice that some items couldn't be updated after an update, click it to see which items failed.
• Check for updates again in the GUI settings and apply them.
• Updates that replace the daemon, the GUI, or the updater itself are applied by the updater after the daemon exits. Don't relaunch Saba-chan while it's applying.
• If that still doesn't help, quit Saba-chan, empty the updates\ folder, and try again.

4. Discord Bot / Cloud Pairing

4.1 Bot doesn't respond

• Write the prefix (default !saba), a space, then the server name and command. Example: !saba minecraft status.
• Pairing must be completed in the GUI so that .node_token is saved.
• Saba-chan (the daemon) must be running. The bot runs in the cloud, but commands are executed by the daemon on this PC.
• If the daemon can't connect to the relay, check recent warnings under Settings → Advanced → "Diagnostics" in the GUI. If you see "older than relay minimum", update Saba-chan.
• Make sure the official bot is invited to your guild and isn't asleep. If it is, wake it with /saba wake.

4.2 Pairing code is "expired"

A pairing code is valid for only 5 minutes. Issue a new code from the GUI.

4.3 Relay connection rejected with 401

4.4 Music commands don't work

• In the GUI Discord page, check that music is enabled in that server's (guild's) settings.
• The person issuing the command must already be in a Discord voice channel. If the bot can't join the voice channel, check the bot's channel permissions.
• Playback is handled by the official music server, so you don't need ffmpeg or yt-dlp on your PC.

5. Data / Configuration Recovery

5.1 config.json is corrupted

• The daemon moves a corrupted config.json aside as config.json.corrupt-<timestamp> and automatically restores from config.json.bak (the last good copy).
• If .bak is also missing or corrupted, it starts with defaults. Every setting, including your Discord integration settings, is reset, so re-enter the values you need in the GUI using the moved .corrupt- file as a reference.
• The server list (instances\) and .node_token are separate from config.json, so they are kept.

5.2 Full reset

1. Quit the Saba-chan GUI, CLI, and daemon
2. Back up and delete the entire %APPDATA%\saba-chan folder
3. Launch Saba-chan → it rebuilds from defaults

Caution: If you installed servers in the default location, the game server files and backups are inside %APPDATA%\saba-chan\instances\ and are deleted along with it. Game files survive only if you chose a server folder outside this folder.

6. Where Do I Find the Logs?

You can change the daemon's log level with the RUST_LOG environment variable when running the daemon directly (default info).

7. Issue Report Checklist

Before opening a new issue, please confirm and attach the following.

1. Saba-chan version (saba-chan-cli version, or GUI Diagnostics).
2. Reproduction steps.
3. Relevant logs (excerpts trimmed by timestamp). The output of "Copy" in GUI Diagnostics also helps.
4. OS / build (e.g., Windows 10 x64 21H2).
5. Never attach the token files (.ipc_token, .node_token) or their contents.

Repositories:

• Main: github.com/WareAoba/saba-chan/issues
• Modules: github.com/WareAoba/saba-chan-modules/issues
• Extensions: github.com/WareAoba/saba-chan-extensions/issues