Resolución de problemas
Problemas habituales al operar Saba-chan, con pasos de solución basados en el comportamiento real del código.

Resolución de problemas
Este documento se organiza según los síntomas que encuentran realmente los usuarios y explica cómo se comporta el código del demonio junto con los pasos para solucionarlo. Los ejemplos de comandos y las rutas son para Windows. En Linux, la carpeta de datos es ~/.config/saba-chan.
1. El demonio no arranca / la GUI no se conecta
1.1 Conflicto de puerto / el demonio ya está en ejecución
El demonio (saba-core) escucha por defecto en el puerto 57474, solo en 127.0.0.1.
- Solo se ejecuta un demonio por PC. Si ya hay un demonio en ejecución, uno recién lanzado termina de inmediato, y la GUI y la CLI se conectan al que ya está en marcha.
- Si otro programa ocupa el puerto, el demonio lo reintenta 10 veces a intervalos de 2 segundos y luego termina.
# Windows: ver quién lo está usando
Get-NetTCPConnection -LocalPort 57474 | Select-Object OwningProcess
Get-Process -Id <pid>
- Puede comprobar si el demonio está vivo, sin token, en
http://127.0.0.1:57474/health.saba-chan-cli daemon statusmuestra la misma información. - Si sigue habiendo un demonio que no responde, deténgalo con
saba-chan-cli daemon stop. Si aun así no desaparece, ejecuteStop-Process -Name saba-core -Force. - Si necesita cambiar el puerto, edite
gui.ipcPortenconfig.jsony reinicie. O defina una variable de entorno comoSABA_IPC_PORT=57480.
1.2 Discrepancia del token IPC
El demonio crea un .ipc_token nuevo cada vez que arranca. Cuando falla la autenticación (401), la GUI y la CLI vuelven a leer el archivo de token y lo reintentan una vez, así que normalmente se resuelve solo.
Si «autenticación fallida» se repite una y otra vez:
- Compruebe que la GUI y el demonio usan la misma carpeta de datos. Si definió
SABA_DATA_DIRoSABA_TOKEN_PATHsolo para uno de ellos, las ubicaciones del archivo de token difieren. - Cierre la GUI por completo y vuelva a abrirla.
2. El inicio/parada del servidor se comporta de forma extraña
2.1 Hice clic en Detener y no pasa nada durante un rato
Puede ser normal. El demonio actúa en este orden:
- En los servidores con consola, envía el
stop_commanddel módulo a la consola (stdin). En los juegos sin consola, como Palworld, el módulo pide al servidor por REST que guarde y se apague. - Espera a que el servidor termine por sí mismo. Por defecto son 30 segundos; un módulo puede cambiarlo con
[config] stop_timeoutenmodule.toml, y usted puede cambiarlo por servidor con el tiempo de espera de parada de la pestaña Saba-chan de la pantalla del servidor. Aumente el valor si el mundo es grande y guardar tarda. - Si sigue vivo, se fuerza su cierre.
- Durante 30 segundos tras la parada, se suspende la detección de fallos.
Si siempre acaba cerrándose a la fuerza, el servidor no está recibiendo el comando de parada. Compruebe si el comando de parada aparece en la consola del servidor. Ejemplos: stop en Minecraft, quit en Zomboid.
2.2 El servidor vuelve a arrancar una y otra vez
Cuando un servidor termina, el demonio clasifica la causa como detenido por usted / detenido en el juego / fallo / desconocido. Por defecto, el reinicio automático solo se produce en caso de fallo; la espera empieza en 5 segundos y se duplica cada vez, y deja de reiniciar tras más de 3 reinicios en 10 minutos.
Solución:
- Compruebe la clasificación en «Salidas recientes» en la pantalla del servidor.
- Para detener los reinicios, desactive «Reiniciar tras un fallo» en «Reinicio automático» dentro de la pestaña Saba-chan de la pantalla del servidor. Si activó «Reiniciar también en salidas desconocidas», revíselo también.
- Revise los logs de consola del servidor (
instances\<id>\logs\) para ver la causa del fallo. Si es un OOM de Java (OutOfMemoryError), aumente el ajuste de memoria.
2.3 Error de «conflicto de puerto» al iniciar
La comprobación previa al arranque detectó que el puerto del servidor lo está usando otra instancia en ejecución u otro programa. Normalmente sigue vivo un proceso anterior, u otro servidor de juego usa el mismo puerto.
- Busque el proceso que usa ese puerto y deténgalo.
- Si no es posible, cambie el puerto en los ajustes de la instancia e inícielo de nuevo.
- Puede desactivar la propia comprobación con «Detección de conflicto de puertos» en los ajustes de la GUI (
gui.portConflictCheck), pero no se recomienda.
2.4 «Se requiere aceptación» (EULA de Minecraft, etc.)
En los juegos cuyo módulo declara condiciones (p. ej., el EULA de Minecraft), debe leerlas y aceptarlas antes de que el servidor pueda arrancar. Mientras no lo haga, el inicio se bloquea con agreement_required.
- Cuando inicie el servidor en la GUI, lea las condiciones en el diálogo que aparece, marque la casilla e inícielo.
- No se pueden aceptar condiciones desde Discord. Una vez aceptadas en Saba-chan en su PC, también podrá iniciar el servidor desde Discord.
2.5 Se rechaza el guardado de los ajustes del servidor
unknown_setting: La clave no es ni un campo común de instancia ni un ajuste declarado por el módulo. Es una errata o un ajuste de otro juego.validation_failed/invalid_format: El rango o el formato del valor no coincide con la declaración del módulo. Corrija el campo indicado en el error.- «Se guardaron los ajustes, pero no se pudo actualizar el archivo de configuración del juego»: Los ajustes se guardaron, pero el módulo no pudo editar el archivo de configuración del juego. Asegúrese de que el archivo del juego no esté bloqueado por otro programa y vuelva a guardar.
2.6 Un componente no verificado no se ejecuta
Los módulos y extensiones que no se instalaron desde el catálogo oficial, o cuyos archivos cambiaron después, se marcan como «no verificados». Saba-chan no los analiza con antivirus. En Windows se ejecutan aislados con AppContainer y en Linux con bubblewrap; donde no se puede aislar (Linux sin bubblewrap o donde no se puede usar, y macOS), solo se ejecutan después de que des tu consentimiento para sus archivos actuales. Si se bloquea la ejecución, se muestra uno de estos códigos.
| Código | Significado | Solución |
|---|---|---|
launch_outside_instance | El módulo intentó ejecutar un programa fuera de la carpeta del servidor | Compruebe de dónde procede el módulo |
sandbox_unavailable | No se pudo preparar el entorno aislado en este PC | Vea más abajo |
Con sandbox_unavailable, la GUI pregunta «¿Ejecutar sin aislamiento?». Permítalo solo para componentes de confianza. Si lo permite, ese componente puede acceder a todos los archivos y a la red con los permisos de su cuenta. El consentimiento solo puede darse en este PC, y se vuelve a pedir si cambian los archivos del componente. Puede retirar el consentimiento en Ajustes → Seguridad → «Ejecutar sin aislamiento».
La solución más segura es reinstalar el módulo o la extensión desde el catálogo oficial. Los componentes verificados se saltan estas comprobaciones.
3. Problemas de instalación / actualización
3.1 La instalación falla a medias
- Cuando el instalador se detiene, la pantalla de error muestra un código de causa (
fetch_failed,download_failed,extract_failed,elevation_failed,installer_outdated) y la ruta del log. El log se escribe en%TEMP%\saba-chan-installer.log. installer_outdatedsignifica que el instalador es más antiguo que la última versión. Descargue y ejecute el instalador más reciente.- Si es un problema de red, compruebe su conexión y luego haga clic en Reintentar o vuelva a ejecutar el instalador.
- Un fallo al preparar el runtime de Python no detiene la instalación. El demonio lo vuelve a preparar en el primer arranque, y volver a ejecutar el instalador elimina un runtime dañado y lo descarga de nuevo.
3.2 El progreso de instalación del servidor no aparece o se queda atascado (para desarrolladores de módulos)
El progreso de instalación del servidor está disponible en GET /api/provision-progress/:name.
- Compruebe que el módulo/la extensión escribe el progreso en stderr con el formato
PROGRESS:{json}. - Compruebe que el JSON es válido (escape las comillas dobles y los saltos de línea dentro de
message). - El progreso correcto se elimina 5 segundos después de terminar, así que si sondea demasiado tarde lo verá ya vacío. El progreso fallido permanece hasta que el usuario lo descarta y, si era un servidor recién creado, al descartarlo se elimina esa instancia.
3.3 Una actualización no se aplica
Las actualizaciones se comprueban contra la información de versiones firmada que proporciona el relay de Saba-chan, y el hash de cada archivo se verifica antes de aplicarla. Si la firma o un hash no coinciden, no se aplica nada.
- Si tras una actualización ve un aviso de que algunos elementos no se pudieron actualizar, haga clic en él para ver cuáles fallaron.
- Vuelva a buscar actualizaciones en los ajustes de la GUI y aplíquelas.
- Las actualizaciones que reemplazan el demonio, la GUI o el propio instalador las aplica
saba-chan-installerdespués de que el demonio termine. No vuelva a abrir Saba-chan mientras se aplican. - Si aun así no se resuelve, cierre Saba-chan, vacíe la carpeta
updates\e inténtelo de nuevo.
4. Bot de Discord / emparejamiento en la nube
4.1 El bot no responde
- Escriba el prefijo (por defecto
Saba-chan), un espacio y luego el nombre del servidor y el comando. Ejemplo:Saba-chan minecraft status. - El emparejamiento debe haberse completado en la GUI para que se guarde
.node_token. - Saba-chan (el demonio) debe estar en ejecución. El bot funciona en la nube, pero los comandos los ejecuta el demonio de este PC.
- Si el demonio no puede conectarse al relay, revise las advertencias recientes en Ajustes → Solución de problemas → «Diagnóstico» de la GUI. Si ve «older than relay minimum», actualice Saba-chan.
- Asegúrese de que el bot oficial está invitado a su servidor de Discord y no está en reposo. Si lo está, despiértelo con
/saba wake.
4.2 El código de emparejamiento aparece como «caducado»
Un código de emparejamiento solo es válido durante 5 minutos. Genere un código nuevo desde la GUI.
4.3 Conexión con el relay rechazada con 401
| Error | Causa | Solución |
|---|---|---|
TOKEN_REPLACED | Al emparejar en otro sitio se eligió este PC con Volver a conectar, lo que reemplazó el token de este PC | Vuelva a emparejar si quiere seguir usando este PC |
INVALID_TOKEN / NODE_NOT_FOUND | .node_token es incorrecto o se eliminó en el servidor | Vuelva a emparejar (invalida el token existente) |
MISSING_TOKEN / INVALID_TOKEN_FORMAT | Falta el archivo de token o tiene un formato incorrecto | Vuelva a emparejar |
4.4 Los comandos de música no funcionan
- En la página de Discord de la GUI, compruebe que la música está activada en los ajustes de ese servidor de Discord.
- Quien da el comando debe estar ya en un canal de voz de Discord. Si el bot no puede unirse al canal de voz, revise los permisos del bot en ese canal.
- La reproducción la gestiona el servidor de música oficial, así que no necesita ffmpeg ni yt-dlp en su PC.
4.5 No se puede conectar a un daemon remoto
| Mensaje | Qué hacer |
|---|---|
Ese PC no está abierto a conexiones remotas | En el PC servidor, Permitir conexiones remotas está desactivado en Ajustes → Conexión → Daemon remoto. Actívelo y guarde |
No se pudo llegar al daemon remoto | Compruebe que el PC servidor y su Saba-chan estén encendidos y con internet. Si no se puede llegar directamente, la conexión pasa por la nube de Saba-chan, así que no hace falta abrir puertos |
Este PC no está conectado a Discord | Empareje los dos PC con la misma cuenta de Discord |
El daemon remoto ya no acepta este PC | El PC servidor lo desconectó. Pulse Conectar de nuevo en su PC |
El puerto ya está en uso | Otro programa usa el mismo puerto. Cambie el puerto |
Esto solo se puede hacer en ese PC | Cosas como las actualizaciones o el inicio al iniciar sesión no se pueden hacer en remoto |
4.6 Un enlace de Saba-chan web no se abre
- Un enlace se abre una sola vez, dentro de 5 minutos. Pida otro con
/saba web. - Si ve
No se pudo conectar con tu PC, compruebe que Saba-chan esté en marcha en el PC y que sea la última versión. - En un enlace abierto sin PC, los menús de servidores, módulos y PC están bloqueados. Instale la app, ejecute
/saba connecty pida un enlace nuevo. - Cerrar la pestaña o recargar termina la sesión. Es lo normal.
5. Recuperación de datos / configuración
5.1 config.json está dañado
- El demonio aparta un
config.jsondañado comoconfig.json.corrupt-<marca de tiempo>y restaura automáticamente a partir deconfig.json.bak(la última copia válida). - Si
.baktambién falta o está dañado, arranca con los valores predeterminados. Se restablecen todos los ajustes, incluidos los de la integración con Discord, así que vuelva a introducir en la GUI los valores que necesite tomando como referencia el archivo.corrupt-apartado. - La lista de servidores (
instances\) y.node_tokenson independientes deconfig.json, así que se conservan.
5.2 Restablecimiento completo
1. Cierre la GUI, la CLI y el demonio de Saba-chan
2. Haga una copia de seguridad de toda la carpeta %APPDATA%\saba-chan y elimínela
3. Inicie Saba-chan → se reconstruye con los valores predeterminados
Atención: si instaló servidores en la ubicación predeterminada, los archivos de los servidores de juego y las copias de seguridad están dentro de %APPDATA%\saba-chan\instances\ y se eliminan con ella. Los archivos de juego solo sobreviven si eligió una carpeta de servidor fuera de esta carpeta.
6. ¿Dónde encuentro los logs?
| Ubicación | Contenido |
|---|---|
%APPDATA%\saba-chan\logs\saba-chan-*.log | Log de la GUI. También contiene la salida de un demonio iniciado por la GUI |
| Ventana de consola del demonio en la GUI | Log del demonio (búfer en memoria, últimas 10 000 líneas) |
| GUI Ajustes → Solución de problemas → Diagnóstico | Estado del demonio y advertencias/errores recientes. No contiene contraseñas ni tokens |
%APPDATA%\saba-chan\instances\<id>\logs\ | Logs de consola del servidor (console.log, sessions\) |
| Pestaña Consola de la GUI | Salida del servidor de juego por instancia |
%APPDATA%\saba-chan\audit.log | Registro de inicios/paradas/comandos de servidores (con origen, secretos ocultos) |
%TEMP%\saba-chan-installer.log | Log del instalador |
Puede cambiar el nivel de log del demonio con la variable de entorno RUST_LOG cuando ejecuta el demonio directamente (por defecto info).
7. Lista de comprobación para informar de un problema
Antes de abrir una incidencia nueva, compruebe y adjunte lo siguiente.
- Versión de Saba-chan (
saba-chan-cli version, o el Diagnóstico de la GUI). - Pasos para reproducirlo.
- Logs relevantes (fragmentos recortados por marca de tiempo). La salida de «Copiar» en el Diagnóstico de la GUI también ayuda.
- SO / compilación (p. ej., Windows 10 x64 21H2).
- No adjunte nunca los archivos de token (
.ipc_token,.node_token) ni su contenido.
Repositorios:
- Principal: github.com/WareAoba/saba-chan/issues
- Módulos: github.com/WareAoba/saba-chan-modules/issues
- Extensiones: github.com/WareAoba/saba-chan-extensions/issues