문제 해결
사바쨩 운영 중 자주 마주치는 문제와, 실제 코드 동작 기준의 해결 절차.

문제 해결
이 문서는 사용자가 겪는 실제 증상별로 데몬 코드가 어떻게 동작하는지와 해결 절차를 정리합니다. 명령 예시와 경로는 Windows 기준입니다. 리눅스에서는 데이터 폴더가 ~/.config/saba-chan입니다.
1. 데몬이 뜨지 않음 / GUI가 연결되지 않음
1.1 포트 충돌 / 데몬이 이미 실행 중
데몬(saba-core)의 기본 포트는 57474이며 127.0.0.1에만 열립니다.
- 데몬은 PC당 하나만 실행됩니다. 이미 데몬이 떠 있으면 새로 띄운 데몬은 바로 종료하고, GUI·CLI는 떠 있는 데몬에 연결합니다.
- 다른 프로그램이 포트를 쓰고 있으면 데몬은 2초 간격으로 10번 다시 시도한 뒤 종료합니다.
# Windows: 누가 쓰는지 확인
Get-NetTCPConnection -LocalPort 57474 | Select-Object OwningProcess
Get-Process -Id <pid>
- 데몬이 살아 있는지는 토큰 없이
http://127.0.0.1:57474/health로 확인할 수 있습니다.saba-chan-cli daemon status도 같은 정보를 보여 줍니다. - 응답이 없는 데몬이 남아 있다면
saba-chan-cli daemon stop으로 끄세요. 그래도 남으면Stop-Process -Name saba-core -Force. - 포트 변경이 필요하면
config.json의gui.ipcPort를 수정한 뒤 재기동합니다. 또는SABA_IPC_PORT=57480같이 환경변수를 넣습니다.
1.2 IPC 토큰 불일치
데몬은 켜질 때마다 .ipc_token을 새로 만듭니다. GUI와 CLI는 인증이 실패(401)하면 토큰 파일을 다시 읽고 한 번 더 시도하므로 보통은 저절로 해결됩니다.
그래도 "인증 실패" 가 반복된다면:
- GUI와 데몬이 같은 데이터 폴더를 보고 있는지 확인합니다.
SABA_DATA_DIR이나SABA_TOKEN_PATH를 한쪽에만 넣었다면 토큰 파일 위치가 달라집니다. - GUI를 완전히 종료한 뒤 다시 실행합니다.
2. 서버 시작/정지가 이상하게 동작
2.1 정지를 눌렀는데 한동안 아무 반응 없음
정상일 수 있습니다. 데몬은 다음 순서로 처리합니다.
- 콘솔이 있는 서버는 모듈의
stop_command를 콘솔(stdin)로 보냅니다. Palworld처럼 콘솔이 없는 게임은 모듈이 REST로 저장·종료를 요청합니다. - 서버가 스스로 꺼지기를 기다립니다. 기본 30초이며, 모듈이
module.toml의[config] stop_timeout으로 바꾸고, 사용자는 서버 화면 사바쨩 탭의 정지 대기 시간으로 서버마다 바꿀 수 있습니다. 월드가 커서 저장이 오래 걸리면 늘리세요. - 그래도 살아 있으면 강제 종료합니다.
- 정지 후 30초 동안은 크래시 감지를 하지 않습니다.
매번 강제 종료까지 간다면 서버가 정지 명령을 받지 못하는 것입니다. 서버 콘솔에서 정지 명령이 찍히는지 확인하세요. 예: Minecraft stop, Zomboid quit.
2.2 서버가 계속 다시 켜짐
서버가 꺼지면 데몬이 종료 원인을 직접 끔 / 게임 안에서 끔 / 크래시 / 알 수 없음으로 판정합니다. 자동 재시작은 기본적으로 크래시일 때만 동작하고, 대기 시간이 5초부터 두 배씩 늘고, 10분 안에 3번을 넘으면 재시작을 멈춥니다.
해결:
- 서버 화면의 "최근 종료 기록" 에서 판정 결과를 확인합니다.
- 다시 켜지 않게 하려면 서버 화면 사바쨩 탭의 "자동 재시작" 에서 "크래시 나면 다시 켜기" 를 끕니다. "이유를 모를 때도 다시 켜기" 를 켜 두었다면 그것도 확인하세요.
- 서버 콘솔 기록(
instances\<id>\logs\)에서 크래시 원인을 확인합니다. Java OOM(OutOfMemoryError)이면 메모리 설정을 늘리세요.
2.3 시작할 때 "포트 충돌" 오류
시작 전 점검에서 그 서버의 포트를 실행 중인 다른 인스턴스나 다른 프로그램이 쓰고 있는 것이 확인된 경우입니다. 대개 이전 프로세스가 남아 있거나, 같은 포트를 다른 게임 서버가 쓰는 중입니다.
- 해당 포트를 쓰는 프로세스를 확인한 뒤 종료합니다.
- 불가능하면 인스턴스 설정에서 포트를 바꾸고 다시 시작합니다.
- 검사 자체는 GUI 설정의 "포트 충돌 검사"(
gui.portConflictCheck)로 끌 수 있지만 권장하지 않습니다.
2.4 "약관 동의가 필요합니다" (Minecraft EULA 등)
모듈이 약관을 선언한 게임(예: Minecraft EULA)은 사용자가 원문을 읽고 동의해야 서버를 켤 수 있습니다. 동의하지 않으면 시작이 agreement_required로 막힙니다.
- GUI에서 서버를 켜면 나오는 동의 창에서 원문을 읽고 체크한 뒤 "동의하고 켜기" 를 누릅니다.
- 디스코드에서는 동의할 수 없습니다. PC의 사바쨩에서 한 번 동의하면 그 뒤로는 디스코드에서도 켤 수 있습니다.
2.5 서버 설정 저장이 거부됨
unknown_setting: 인스턴스 공통 항목도, 그 모듈이 선언한 설정도 아닌 키입니다. 오타이거나 다른 게임의 설정입니다.validation_failed/invalid_format: 값의 범위나 형식이 모듈 선언과 다릅니다. 오류에 표시된 항목을 고치세요.- "설정은 저장했지만 게임 설정 파일에 쓰지 못했어요": 설정은 저장됐지만 모듈이 게임 설정 파일을 고치지 못했습니다. 게임 파일이 다른 프로그램에 잠겨 있지 않은지 확인하고 다시 저장하세요.
2.6 확인되지 않은 구성요소가 실행되지 않음
공식 카탈로그에서 받지 않았거나 받은 뒤 파일이 바뀐 모듈·익스텐션은 "확인 안 됨" 으로 표시됩니다. 사바쨩은 이들을 백신으로 검사하지 않습니다. Windows에서는 AppContainer, 리눅스에서는 bubblewrap으로 격리해 실행하고, 격리할 수 없는 환경(bubblewrap이 없거나 쓸 수 없는 리눅스, macOS)에서는 현재 파일에 대해 사용자가 동의한 뒤에만 실행합니다. 실행이 막히면 다음 코드 중 하나가 표시됩니다.
| 코드 | 뜻 | 해결 |
|---|---|---|
launch_outside_instance | 모듈이 서버 폴더 밖의 프로그램을 실행하려 함 | 모듈 출처를 확인하세요 |
sandbox_unavailable | 이 PC에서 격리 환경을 준비하지 못함 | 아래 참고 |
sandbox_unavailable 일 때 GUI는 "격리 없이 실행할까요?" 를 묻습니다. 믿을 수 있는 구성요소일 때만 허용하세요. 허용하면 그 구성요소는 내 계정 권한으로 모든 파일과 네트워크에 접근할 수 있습니다. 동의는 이 PC에서만 할 수 있고, 구성요소 파일이 바뀌면 다시 묻습니다. 동의는 GUI 설정 → 고급의 "격리 없이 돌리기" 에서 취소할 수 있습니다.
가장 확실한 방법은 모듈·익스텐션을 공식 카탈로그에서 다시 설치하는 것입니다. 확인된 구성요소는 이 검사를 거치지 않습니다.
3. 설치·업데이트 관련
3.1 설치가 중간에 실패
- 인스톨러가 멈추면 오류 화면에 원인 코드(
fetch_failed,download_failed,extract_failed,elevation_failed,installer_outdated)와 로그 경로가 표시됩니다. 로그는%TEMP%\saba-chan-installer.log에 남습니다. installer_outdated는 인스톨러가 최신 릴리스보다 오래됐다는 뜻입니다. 최신 인스톨러를 받아 실행하세요.- 네트워크 문제라면 연결을 확인한 뒤 다시 시도를 누르거나 인스톨러를 다시 실행합니다.
- Python 런타임 준비는 실패해도 설치를 멈추지 않습니다. 사바쨩을 처음 실행할 때 데몬이 다시 준비하고, 인스톨러를 다시 실행하면 손상된 런타임을 지우고 새로 받습니다.
3.2 서버 설치 진행이 보이지 않거나 멈춤 (모듈 개발자용)
서버 설치 진행은 GET /api/provision-progress/:name으로 볼 수 있습니다.
- 모듈/익스텐션이 진행을 stderr에
PROGRESS:{json}형식으로 찍는지 확인합니다. - JSON이 유효한지 확인합니다(
message안의 큰따옴표·개행 이스케이프). - 성공한 진행 정보는 5초 뒤 사라지므로, 너무 늦게 폴링하면 이미 비어 있을 수 있습니다. 실패한 정보는 사용자가 닫을 때까지 남고, 새로 만들던 서버였다면 닫을 때 그 인스턴스가 지워집니다.
3.3 업데이트가 적용되지 않음
업데이트는 서버쨩이 제공하는 서명된 릴리스 정보로 확인하고, 파일마다 해시를 검사한 뒤 적용합니다. 서명이나 해시가 맞지 않으면 적용하지 않습니다.
- 업데이트 뒤 "업데이트하지 못한 항목이 있어요" 알림이 뜨면 눌러서 실패한 항목을 확인합니다.
- GUI 설정에서 업데이트를 다시 확인하고 적용합니다.
- 데몬·GUI·설치 프로그램 자신을 바꾸는 업데이트는 데몬이 종료된 뒤 설치 프로그램(
saba-chan-installer)이 적용합니다. 적용 중에는 사바쨩을 다시 실행하지 마세요. - 그래도 안 되면 사바쨩을 종료하고
updates\폴더를 비운 뒤 다시 시도합니다.
4. 디스코드 봇 / 클라우드 페어링
4.1 봇이 반응 없음
- 접두사(기본
사바쨩) 바로 뒤에 공백을 두고 서버 이름과 명령을 씁니다. 예:사바쨩 minecraft status. - GUI에서 페어링이 완료되어
.node_token이 저장된 상태여야 합니다. - 사바쨩(데몬)이 켜져 있어야 합니다. 봇은 클라우드에서 돌지만, 명령은 이 PC의 데몬이 실행합니다.
- 데몬이 서버쨩에 연결하지 못하면 GUI 설정 → 고급의 "진단 정보" 에서 최근 경고를 확인합니다. "older than relay minimum" 이 보이면 사바쨩을 업데이트하세요.
- 디스코드 서버에 공식 봇이 초대되어 있는지, 봇이 잠자기 상태가 아닌지 확인하세요. 잠자기 상태라면
/사바쨩 기상으로 깨웁니다.
4.2 페어링 코드가 "expired"
페어링 코드는 5분 동안만 유효합니다. GUI에서 새 코드를 발급하세요.
4.3 서버쨩 연결이 401로 거부됨
| 오류 | 원인 | 해결 |
|---|---|---|
TOKEN_REPLACED | 다른 곳에서 페어링하며 다시 연결로 이 PC를 골라 이 PC의 토큰이 교체됨 | 이 PC를 계속 쓰려면 다시 페어링 |
INVALID_TOKEN / NODE_NOT_FOUND | .node_token이 잘못됐거나 서버에서 삭제됨 | 다시 페어링 (기존 토큰은 무효화) |
MISSING_TOKEN / INVALID_TOKEN_FORMAT | 토큰 파일이 없거나 형식이 깨짐 | 다시 페어링 |
4.4 노래하는 사바쨩 명령어가 먹히지 않음
- GUI 디스코드 화면의 그 디스코드 서버 설정에서 노래하는 사바쨩이 켜져 있는지 확인합니다.
- 명령을 친 사람이 디스코드 음성 채널에 먼저 들어가 있어야 합니다. 봇이 음성 채널에 들어가지 못하면 봇의 채널 권한을 확인하세요.
- 재생은 공식 음악 서버가 처리하므로 사용자 PC에 ffmpeg/yt-dlp가 없어도 됩니다.
4.5 원격 데몬에 붙지 못함
| 보이는 말 | 조치 |
|---|---|
그 PC가 원격 연결을 열지 않았어요 | 서버 PC에서 설정 → 연결 → 원격 데몬의 원격 연결 받기가 꺼져 있습니다. 켜고 저장합니다 |
원격 데몬에 닿지 못했어요 | 서버 PC와 그 PC의 사바쨩이 켜져 있고 인터넷에 연결돼 있는지 확인합니다. 바로 닿지 않으면 사바쨩 클라우드를 거쳐 붙으므로 포트포워딩이 꼭 필요하지는 않습니다 |
이 PC가 디스코드에 연결돼 있지 않아요 | 두 PC 모두 같은 디스코드 계정으로 페어링합니다 |
원격 데몬이 이 PC를 더는 받지 않아요 | 서버 PC에서 연결을 끊었습니다. 내 PC에서 연결을 다시 누릅니다 |
포트를 이미 쓰고 있어요 | 다른 프로그램이 같은 포트를 씁니다. 포트를 바꿉니다 |
그 PC에서 직접 해야 하는 일이에요 | 업데이트, 자동 실행처럼 원격으로 할 수 없는 일입니다 |
4.6 사바쨩 웹 링크가 열리지 않음
- 링크는 한 번만, 5분 안에 열 수 있습니다.
/사바쨩 웹으로 새 링크를 받습니다. PC에 연결하지 못했어요가 나오면 PC의 사바쨩이 켜져 있고 최신 버전인지 확인합니다.- PC 없이 연 링크에서는 서버·모듈·PC 메뉴가 잠겨 있습니다. 앱을 설치하고
/사바쨩 연결을 한 뒤 새 링크를 받습니다. - 탭을 닫거나 새로 고치면 세션이 끝납니다. 이것은 정상 동작입니다.
5. 데이터·설정 복구
5.1 config.json이 깨짐
- 데몬은 깨진
config.json을config.json.corrupt-<시각>으로 옮기고config.json.bak(직전 정상본)에서 자동으로 복구합니다. .bak도 없거나 깨졌다면 기본값으로 시작합니다. 이때 디스코드 연동 설정 등 모든 설정이 기본값이 되므로, 옮겨진.corrupt-파일에서 필요한 값을 GUI로 다시 입력하세요.- 서버 목록(
instances\)과.node_token은config.json과 별개라 그대로 유지됩니다.
5.2 전체 초기화
1. 사바쨩 GUI · CLI · 데몬 종료
2. %APPDATA%\saba-chan 폴더를 통째로 백업 후 삭제
3. 사바쨩 실행 → 기본 상태로 리빌드
주의: 서버를 기본 위치에 설치했다면 게임 서버 파일과 백업이 %APPDATA%\saba-chan\instances\ 안에 있으므로 함께 삭제됩니다. 서버 폴더를 직접 지정해 이 폴더 밖에 설치한 경우에만 게임 파일이 남습니다.
6. 로그 어디서 보나요
| 위치 | 내용 |
|---|---|
%APPDATA%\saba-chan\logs\saba-chan-*.log | GUI 로그. GUI가 띄운 데몬의 출력도 함께 남음 |
| GUI 데몬 콘솔 창 | 데몬 로그 (메모리 버퍼, 최근 10,000줄) |
| GUI 설정 → 문제 해결 → 진단 정보 | 데몬 상태와 최근 경고·오류. 비밀번호와 토큰은 들어가지 않음 |
%APPDATA%\saba-chan\instances\<id>\logs\ | 서버 콘솔 기록 (console.log, sessions\) |
| GUI 콘솔 탭 | 인스턴스별 게임 서버 출력 |
%APPDATA%\saba-chan\audit.log | 서버 시작·정지·명령 기록 (출처 포함, 비밀값은 가림) |
%TEMP%\saba-chan-installer.log | 인스톨러 로그 |
데몬 로그 수준은 데몬을 직접 실행할 때 RUST_LOG 환경변수로 바꿀 수 있습니다(기본 info).
7. 이슈 리포트 체크리스트
새 이슈를 열기 전에 다음 정보를 확인·첨부해 주세요.
- 사바쨩 버전 (
saba-chan-cli version, 또는 GUI 진단 정보). - 재현 단계.
- 관련 로그 (시간대 기준으로 자른 발췌). GUI 진단 정보의 "복사" 결과도 도움이 됩니다.
- 운영체제 / 빌드 (Windows 10 x64 21H2 등).
- 토큰 파일(
.ipc_token,.node_token)과 그 내용은 절대 첨부하지 마세요.
리포지토리: