Troubleshooting

This document organizes things by the symptoms users actually experience and explains how the daemon code behaves plus the steps to fix it.

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

1.1 Port Conflict (EADDRINUSE)

The default daemon port is 57474. If another process is already holding it, the daemon exits immediately.

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

• If a previously crashed Saba-chan is still hanging around, run Stop-Process -Name saba-chan -Force.
• If you need to change the port, edit settings.json.ipcPort and restart. Or inject an env var like SABA_IPC_PORT=57480.

1.2 IPC Token Mismatch

If the GUI keeps reporting "authentication failed," the GUI session and the daemon session may be holding different .ipc_token values.

• Fully stop the daemon first.
• Delete %APPDATA%\saba-chan\.ipc_token.
• Restart the daemon → a new UUID is written → also restart the GUI so it picks up the new token.

In a development environment you can temporarily disable verification with SABA_AUTH_DISABLED=1, but never use it in production.

2. Server Start/Stop Behaves Strangely

2.1 I clicked Stop and nothing happens for 30 seconds

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

1. Send the module's stop_command, then wait 30 seconds gracefully (overridable via graceful_stop_timeout in module.toml).
2. If it's still alive, force-kill 5 seconds later.
3. After stopping, suppress automatic crash detection for 30 seconds as a cooldown.

(For the actual constants, see src/supervisor/mod.rs.)

If a process never responds and always ends up at the force-kill stage, check that stop_command is correct. Examples: Minecraft stop, Palworld Shutdown, Zomboid quit.

2.2 Server is stuck in an infinite restart loop

When the state machine transitions Running → Crashed, automatic recovery is attempted according to the restart policy. The default policy is unless-stopped, so unless the user stops it explicitly, restarts will keep going.

Resolution:

• Click an explicit "Stop" in the GUI. That state is excluded from restart targets.
• Or change [docker].restart in module.toml (or in the instance's ext_data) to "no" or "on-failure".
• Check the logs (%APPDATA%\saba-chan\logs\) for the crash cause. For a Java OOM (OutOfMemoryError), increase -Xmx or follow the diagnose output.

2.3 "Port in use" error right after start

The server.pre_start hook (or the runtime) detected a port conflict. 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 restart.

3. Installation / Update Issues

3.1 Installation fails midway

Both the installer and module downloads default to streaming download + retry. Once the network recovers, re-running will repair only the damaged parts.

• Installer: When re-run, setup_python_with_repair() / setup_node_with_repair() are invoked and only files whose checksums don't match are re-downloaded.
• Module install_server: Even on failure, intact files inside installation_dir are preserved. Clicking "Install" again will pick up where it left off.

3.2 GET /api/provision-progress/:name is empty

• Verify that the module/extension code emits the correct PROGRESS: prefix.
• Verify the JSON is valid (escape double quotes and newlines inside message).
• The tracker is removed 5 seconds after completion, so polling too late will see it already empty.

3.3 After applying an update, the version is unchanged

If the component versions recorded in installed-manifest.json don't match the actual files on disk, the updater may skip them.

• Run "Force update check" in the GUI.
• If it doesn't help, empty the updates/ folder and try again.

4. Discord Bot / Cloud Pairing

4.1 Bot doesn't respond

• The prefix (default 사바쨩) must be followed by a space before the command.
• Confirm the GUI has finished pairing and that .node_token has been issued.
• Check %APPDATA%\saba-chan\logs\daemon-*.log for relay long-poll connection errors.
• The bot itself runs on the relay server, so there is no local bot-process log on your PC. First, make sure the official bot is invited to your guild.

4.2 Pairing code is "expired"

The 5-minute TTL elapsed. Issue a new code from the GUI. The code is fixed at 32 characters, pollSecret at 48, and they're separated — so even if someone sees your pairing code, the token cannot be hijacked without pollSecret.

4.3 Relay request returns 401 / 409

4.4 Music commands don't work

• Confirm musicEnabled: true.
• If musicChannelId is set, the commands only work in that text channel.
• Verifying yt-dlp / ffmpeg is the responsibility of the music extension's daemon.startup hook. If a warning badge shows up on the extension status in the GUI, follow the instructions to install them.

5. Data / Configuration Recovery

5.1 settings.json is corrupted → daemon won't boot

• Stop the daemon and delete settings.json. On the next boot, it will be regenerated with defaults.
• The instance list (instances.json) is preserved, so your servers survive.

5.2 Full reset

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

Game server files (the path you specified in installation_dir) are not deleted alongside, as long as they live outside this folder.

6. Where Do I Find the Logs?

The log level can be adjusted via settings.json.logLevel (default info). When filing an issue, please attach a reproduction log captured at debug level.

7. Issue Report Checklist

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

1. Saba-chan version (GET /health or "About" in the GUI).
2. Reproduction steps.
3. Relevant log files (excerpts trimmed by timestamp).
4. OS / build (e.g., Windows 10 x64 21H2).
5. For pairing-related issues, never attach the token itself — include only the hostId.

Repositories:

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