문제 해결
이 페이지에서는 흔한 설치 및 실행 문제를 Q&A 형식으로 다룹니다. 여기에 없는 문제라면 관련 로그를 모아 GitHub 저장소에 이슈를 열어 주세요.
앱이 포트가 이미 사용 중이라고 표시하는 이유는?
로컬 백엔드는 기본적으로 127.0.0.1:8000에서 수신 대기합니다. 다른
프로그램이 해당 포트를 점유하면 사이드카가 시작할 수 없습니다. 충돌하는
프로그램을 종료하거나, 환경 변수 NEOTA_PORT로 다른 포트를 지정해
서버를 시작하세요. 앱의 오류 메시지에는 포트 번호와 충돌 해결에 필요한
세부 정보가 포함됩니다.
백엔드 사이드카가 시작되지 않습니다
데스크톱 앱은 백엔드를 내장 Node.js 사이드카로 실행합니다. 시작에 실패하면 앱 창에 연결 오류가 표시됩니다. 다음을 확인하세요.
- 다른 NeoTavern 인스턴스가 이미 실행 중이며 포트를 점유하고 있을 수 있습니다.
- 현재 위치의 데이터 디렉터리에 쓸 수 없을 수 있습니다.
- 백신 또는 방화벽이 내장 Node 런타임을 차단하고 있을 수 있습니다.
원인을 해결한 후 앱을 다시 시작하세요. 앱이 크래시 루프에 빠지면 타사 플러그인과 테마를 로드하기 전에 비활성화하는 세이프 모드 실행을 제안합니다. 이를 사용해 복구하세요.
데이터베이스가 잠겨 있습니다
NeoTavern은 WAL 모드와 busy timeout으로 SQLite를 사용하므로 짧은 동시 접근은 정상적으로 처리됩니다. "database is locked" 오류가 지속된다면 보통 두 번째 앱 인스턴스가 같은 데이터 디렉터리를 열었거나, 백업 또는 가져오기 작업이 아직 실행 중이라는 뜻입니다. 중복 인스턴스를 닫고 오래 걸리는 작업이 끝날 때까지 기다린 뒤 다시 시도하세요.
캐시를 지우려면 어떻게 하나요?
캐시는 data/cache/ 아래에 있으며 완전히 재생성할 수 있습니다.
썸네일, 토크나이저 데이터, 플러그인 의존성 다운로드가 여기에
해당합니다. 캐시를 지워도 원본은 절대 삭제되지 않으며, 원본은
data/files/ 아래에 별도로 저장됩니다. 설정 → 데이터의 유지 관리
컨트롤에서 캐시를 지우고 전체 텍스트 검색 인덱스를 다시 구축할 수
있습니다. 두 작업 모두 실행 전에 제거될 항목의 개수와 크기를
확인합니다.
로그는 어디에 있나요?
로그는 data/logs/server.log에 기록되며 10 MB 단위로 순환됩니다. 로그
파일은 비식별화되어 있습니다. 비밀, API 키, 사용자 메시지 내용은
절대 기록되지 않습니다. 콘솔 출력도 파일과 함께 유지됩니다. 버그를
보고할 때는 관련 로그 줄과 오류 세부 정보에 표시된 추적 ID를 함께
포함하세요.
작동하는 인터페이스로 돌아가려면 어떻게 하나요?
세이프 모드를 사용하세요. 세이프 모드는 타사 테마와 플러그인이 로드되기 전에 접근할 수 있으며 이를 비활성화합니다. 테마나 플러그인이 망가진 후 세이프 모드는 파일을 직접 편집하지 않고도 기본 인터페이스를 복원합니다. 자세한 내용은 테마와 확장 기능을 참조하세요.
보내기 버튼이 비활성화된 이유는?
버튼은 구체적인 이유가 있을 때만 비활성화되며, 그 이유가 버튼 옆에 표시됩니다. 대부분 활성 프로바이더가 없거나 캐릭터가 선택되지 않은 경우입니다. AI 설정에서 프로바이더를 연결하거나 캐릭터를 선택하면 버튼을 사용할 수 있습니다. 빠른 시작을 참조하세요.