Solução de problemas
Problemas comuns ao operar o Saba-chan, com passos de solução baseados em como o código realmente se comporta.

Solução de problemas
Este documento se organiza pelos sintomas que os usuários realmente enfrentam e explica como o código do daemon se comporta, além dos passos para resolver. Os exemplos de comandos e caminhos são para o Windows. No Linux, a pasta de dados é ~/.config/saba-chan.
1. O daemon não inicia / a GUI não consegue se conectar
1.1 Conflito de porta / daemon já em execução
O daemon (saba-core) escuta na porta 57474 por padrão, apenas em 127.0.0.1.
- Só um daemon roda por PC. Se já houver um daemon rodando, um recém-iniciado encerra na hora, e a GUI e a CLI se conectam ao que já está rodando.
- Se outro programa estiver ocupando a porta, o daemon tenta de novo 10 vezes em intervalos de 2 segundos e depois encerra.
# Windows: veja quem está usando a porta
Get-NetTCPConnection -LocalPort 57474 | Select-Object OwningProcess
Get-Process -Id <pid>
- Você pode verificar se o daemon está vivo sem token em
http://127.0.0.1:57474/health.saba-chan-cli daemon statusmostra a mesma informação. - Se um daemon que não responde continuar por aí, pare-o com
saba-chan-cli daemon stop. Se mesmo assim ele não sumir, executeStop-Process -Name saba-core -Force. - Se precisar mudar a porta, edite
gui.ipcPortnoconfig.jsone reinicie. Ou defina uma variável de ambiente comoSABA_IPC_PORT=57480.
1.2 Token IPC não confere
O daemon cria um novo .ipc_token a cada vez que inicia. Quando a autenticação falha (401), a GUI e a CLI releem o arquivo de token e tentam de novo uma vez, então isso costuma se resolver sozinho.
Se "falha de autenticação" continuar se repetindo:
- Confira se a GUI e o daemon olham para a mesma pasta de dados. Se você definiu
SABA_DATA_DIRouSABA_TOKEN_PATHpara apenas um deles, os locais do arquivo de token são diferentes. - Feche a GUI por completo e abra-a de novo.
2. Início/parada do servidor se comporta de forma estranha
2.1 Cliquei em Parar e nada acontece por um tempo
Isso pode ser normal. O daemon trabalha nesta ordem:
- Para servidores com console, ele envia o
stop_commanddo módulo ao console (stdin). Para jogos sem console, como o Palworld, o módulo pede ao servidor que salve e desligue via REST. - Ele espera o servidor encerrar sozinho. O padrão é 30 segundos; um módulo pode mudar isso com
[config] stop_timeoutnomodule.toml, e você pode mudar por servidor em Tempo de espera de parada na aba Saba-chan da tela do servidor. Aumente se o mundo for grande e salvar demorar. - Se ele ainda estiver vivo, é finalizado à força.
- Durante 30 segundos após a parada, a detecção de crash fica suspensa.
Se ele sempre acaba sendo finalizado à força, o servidor não está recebendo o comando de parada. Confira se o comando de parada aparece no console do servidor. Exemplos: stop no Minecraft, quit no Zomboid.
2.2 O servidor fica voltando
Quando um servidor encerra, o daemon classifica a causa como parado por você / parado no jogo / crash / desconhecido. Por padrão, o reinício automático acontece apenas em crashes; a espera começa em 5 segundos e dobra a cada vez, e ele para de reiniciar depois de mais de 3 reinícios em 10 minutos.
Solução:
- Confira a classificação em "Saídas recentes" na tela do servidor.
- Para impedir os reinícios, desligue "Reiniciar após um crash" em "Reinício automático" na aba Saba-chan da tela do servidor. Se você ligou "Reiniciar também em saídas desconhecidas", confira isso também.
- Confira nos logs do console do servidor (
instances\<id>\logs\) a causa do crash. Para um OOM do Java (OutOfMemoryError), aumente a configuração de memória.
2.3 Erro "conflito de porta" ao iniciar
A verificação anterior à inicialização descobriu que a porta do servidor está em uso por outra instância em execução ou por outro programa. Em geral, um processo anterior ainda está por aí, ou outro servidor de jogo usa a mesma porta.
- Encontre o processo que usa essa porta e pare-o.
- Se isso não for possível, mude a porta nas configurações da instância e inicie de novo.
- Você pode desligar a própria verificação com "Detecção de conflito de porta" nas configurações da GUI (
gui.portConflictCheck), mas isso não é recomendado.
2.4 "Concordância necessária" (EULA do Minecraft etc.)
Em jogos cujo módulo declara termos (por exemplo, a EULA do Minecraft), você precisa ler e aceitar os termos antes de o servidor poder iniciar. Até fazer isso, a inicialização fica bloqueada com agreement_required.
- Ao iniciar o servidor na GUI, leia os termos na janela que aparece, marque a caixa e inicie.
- Não é possível aceitar termos pelo Discord. Depois que você os aceita no Saba-chan do seu PC, também pode iniciar o servidor pelo Discord.
2.5 Salvar as configurações do servidor é rejeitado
unknown_setting: A chave não é um campo comum da instância nem uma configuração declarada pelo módulo. É um erro de digitação ou uma configuração de outro jogo.validation_failed/invalid_format: O intervalo ou o formato do valor não corresponde à declaração do módulo. Corrija o campo indicado no erro.- "As configurações foram salvas, mas o arquivo de configuração do jogo não pôde ser atualizado": As configurações foram salvas, mas o módulo não conseguiu editar o arquivo de configuração do jogo. Confira se o arquivo do jogo não está bloqueado por outro programa e salve de novo.
2.6 Um componente não verificado não roda
Módulos e extensões que não foram instalados pelo catálogo oficial, ou cujos arquivos mudaram depois, são marcados como "Não verificado". O Saba-chan não os analisa com antivírus. No Windows eles rodam em um ambiente isolado (AppContainer) e no Linux em bubblewrap; onde não é possível isolar (Linux sem bubblewrap ou em que ele não funciona, e macOS), só rodam depois que você consentir com os arquivos atuais. Se a execução for bloqueada, um destes códigos é exibido.
| Código | Significado | Solução |
|---|---|---|
launch_outside_instance | O módulo tentou executar um programa fora da pasta do servidor | Confira de onde o módulo veio |
sandbox_unavailable | O ambiente isolado não pôde ser preparado neste PC | Veja abaixo |
Em sandbox_unavailable, a GUI pergunta "Executar sem isolamento?". Permita apenas para componentes em que você confia. Se permitir, esse componente poderá acessar todos os arquivos e a rede com as permissões da sua conta. O consentimento só pode ser dado neste PC, e ele é pedido de novo se os arquivos do componente mudarem. Você pode retirar o consentimento em Configurações → Segurança → "Executar sem isolamento".
A solução mais garantida é reinstalar o módulo ou a extensão pelo catálogo oficial. Componentes verificados pulam essas verificações.
3. Problemas de instalação / atualização
3.1 A instalação falha no meio
- Quando o instalador para, a tela de erro mostra um código de causa (
fetch_failed,download_failed,extract_failed,elevation_failed,installer_outdated) e o caminho do log. O log é gravado em%TEMP%\saba-chan-installer.log. installer_outdatedsignifica que o instalador é mais antigo que a release mais recente. Baixe e execute o instalador mais recente.- Para problemas de rede, confira sua conexão e clique em Retry ou execute o instalador de novo.
- Uma falha ao preparar o runtime Python não interrompe a instalação. O daemon o prepara de novo na primeira execução, e executar o instalador de novo apaga um runtime danificado e o baixa do zero.
3.2 O progresso da instalação do servidor não aparece ou fica travado (para desenvolvedores de módulos)
O progresso da instalação do servidor está disponível em GET /api/provision-progress/:name.
- Verifique se o módulo/extensão imprime o progresso no stderr no formato
PROGRESS:{json}. - Verifique se o JSON é válido (escape aspas duplas e quebras de linha dentro de
message). - Um progresso bem-sucedido é removido 5 segundos após a conclusão, então uma consulta tardia demais já o encontra vazio. Um progresso com falha permanece até o usuário dispensá-lo e, se era um servidor recém-criado, dispensá-lo apaga essa instância.
3.3 Uma atualização não é aplicada
As atualizações são verificadas com base em informações de release assinadas fornecidas pelo relay do Saba-chan, e o hash de cada arquivo é conferido antes da aplicação. Se a assinatura ou um hash não conferir, nada é aplicado.
- Se, após uma atualização, aparecer um aviso de que alguns itens não puderam ser atualizados, clique nele para ver quais itens falharam.
- Verifique as atualizações de novo nas configurações da GUI e aplique-as.
- Atualizações que substituem o daemon, a GUI ou o próprio instalador são aplicadas pelo instalador (
saba-chan-installer) depois que o daemon encerra. Não reabra o Saba-chan enquanto ele estiver aplicando. - Se mesmo assim não resolver, feche o Saba-chan, esvazie a pasta
updates\e tente de novo.
4. Bot do Discord / pareamento em nuvem
4.1 O bot não responde
- Escreva o prefixo (padrão
Saba-chan), um espaço e então o nome do servidor e o comando. Exemplo:Saba-chan minecraft status. - O pareamento precisa estar concluído na GUI para que o
.node_tokenesteja salvo. - O Saba-chan (o daemon) precisa estar rodando. O bot roda na nuvem, mas os comandos são executados pelo daemon neste PC.
- Se o daemon não conseguir se conectar ao relay, confira os avisos recentes em Configurações → Solução de problemas → "Diagnóstico" na GUI. Se você vir "older than relay minimum", atualize o Saba-chan.
- Confira se o bot oficial foi convidado para o seu servidor do Discord e não está dormindo. Se estiver, acorde-o com
/saba wake.
4.2 O código de pareamento está "expirado"
Um código de pareamento vale só por 5 minutos. Gere um novo código pela GUI.
4.3 Conexão com o relay rejeitada com 401
| Erro | Causa | Solução |
|---|---|---|
TOKEN_REPLACED | Em outro lugar, um pareamento escolheu este PC com Reconectar, substituindo o token deste PC | Pareie de novo se quiser continuar usando este PC |
INVALID_TOKEN / NODE_NOT_FOUND | O .node_token está errado ou foi removido no servidor | Pareie de novo (invalida o token existente) |
MISSING_TOKEN / INVALID_TOKEN_FORMAT | O arquivo de token está ausente ou malformado | Pareie de novo |
4.4 Os comandos de música não funcionam
- Na página Discord da GUI, confira se a música está ativada nas configurações daquele servidor do Discord.
- Quem envia o comando precisa já estar em um canal de voz do Discord. Se o bot não conseguir entrar no canal de voz, confira as permissões de canal do bot.
- A reprodução é feita pelo servidor de música oficial, então você não precisa de ffmpeg nem yt-dlp no seu PC.
4.5 Não consigo conectar a um daemon remoto
| Mensagem | O que fazer |
|---|---|
Esse PC não está aberto a conexões remotas | No PC servidor, Permitir conexões remotas está desligado em Configurações → Conexão → Daemon remoto. Ative e salve |
Não foi possível alcançar o daemon remoto | Verifique se o PC servidor e o Saba-chan dele estão ligados e com internet. Se não der para alcançar direto, a conexão passa pela nuvem do Saba-chan, então não é preciso abrir portas |
Este PC não está conectado ao Discord | Pareie os dois PCs com a mesma conta do Discord |
O daemon remoto não aceita mais este PC | O PC servidor desconectou este PC. Clique em Conectar de novo no seu PC |
A porta já está em uso | Outro programa usa a mesma porta. Mude a porta |
Isso só pode ser feito naquele PC | Coisas como atualizações e o início ao entrar não podem ser feitas remotamente |
4.6 Um link do Saba-chan web não abre
- Um link abre uma única vez, em até 5 minutos. Peça outro com
/saba web. - Se aparecer
Não foi possível acessar seu PC, verifique se o Saba-chan está rodando no PC e na versão mais recente. - Em um link aberto sem PC, os menus de servidores, módulos e PCs ficam bloqueados. Instale o app, conecte com
/saba connecte peça um novo link. - Fechar a aba ou recarregar encerra a sessão. Isso é normal.
5. Recuperação de dados / configurações
5.1 O config.json está corrompido
- O daemon move um
config.jsoncorrompido paraconfig.json.corrupt-<timestamp>e restaura automaticamente a partir doconfig.json.bak(a última cópia válida). - Se o
.baktambém estiver ausente ou corrompido, ele inicia com os padrões. Todas as configurações, incluindo as da integração com o Discord, são redefinidas, então reinsira na GUI os valores de que precisar usando o arquivo.corrupt-movido como referência. - A lista de servidores (
instances\) e o.node_tokensão separados doconfig.json, então são mantidos.
5.2 Redefinição completa
1. Feche a GUI, a CLI e o daemon do Saba-chan
2. Faça backup e apague a pasta %APPDATA%\saba-chan inteira
3. Abra o Saba-chan → ele se reconstrói com os padrões
Atenção: se você instalou servidores no local padrão, os arquivos dos servidores de jogo e os backups estão dentro de %APPDATA%\saba-chan\instances\ e são apagados junto. Os arquivos de jogo só sobrevivem se você escolheu uma pasta de servidor fora desta pasta.
6. Onde encontro os logs?
| Local | Conteúdo |
|---|---|
%APPDATA%\saba-chan\logs\saba-chan-*.log | Log da GUI. Também contém a saída de um daemon iniciado pela GUI |
| Janela do console do daemon na GUI | Log do daemon (buffer em memória, últimas 10.000 linhas) |
| Configurações da GUI → Solução de problemas → Diagnóstico | Status do daemon e avisos/erros recentes. Não contém senhas nem tokens |
%APPDATA%\saba-chan\instances\<id>\logs\ | Logs do console do servidor (console.log, sessions\) |
| Aba Console da GUI | Saída do servidor de jogo por instância |
%APPDATA%\saba-chan\audit.log | Registro de início/parada/comandos dos servidores (com origem, segredos mascarados) |
%TEMP%\saba-chan-installer.log | Log do instalador |
Você pode mudar o nível de log do daemon com a variável de ambiente RUST_LOG ao executar o daemon diretamente (padrão info).
7. Checklist para relatar um problema
Antes de abrir uma nova issue, confira e anexe o seguinte.
- Versão do Saba-chan (
saba-chan-cli versionou o Diagnóstico da GUI). - Passos para reproduzir.
- Logs relevantes (trechos recortados pelo horário). A saída de "Copiar" no Diagnóstico da GUI também ajuda.
- SO / build (por exemplo, Windows 10 x64 21H2).
- Nunca anexe os arquivos de token (
.ipc_token,.node_token) nem o conteúdo deles.
Repositórios: