문제 해결

빠른 조회

자주 발생하는 문제와 해결 방법 위치:

증상	원인 가능성	확인할 곳
MCP 클라이언트가 연결할 수 없음	오래된 포트 파일 또는 VMark가 실행 중이 아님	MCP 서버 연결 문제
파일이 열리지 않거나 깨진 텍스트가 표시됨	UTF-8이 아닌 인코딩 또는 격리 속성	파일이 열리지 않음
AI 지니가 멈추거나 아무것도 반환하지 않음	제공자 잘못 구성 또는 CLI가 PATH에 없음	AI 지니가 응답하지 않음
키보드 단축키가 아무것도 하지 않음	설정에서 재할당되었거나 시스템 재정의	키보드 단축키가 작동하지 않음
큰 파일에서 에디터 느림	탭당 메모리 + 10,000행 이상 입력 지연	에디터 성능
언어 변경 후에도 메뉴가 영어로	시작 시 메뉴 재구성	메뉴 바가 영어로 표시됨
PDF 내보내기 불완전	이미지 경로 또는 쓰기 권한	내보내기/인쇄 문제
Windows에서 시작이 느림	WebView2 + 안티바이러스 검사	Windows에서 앱 시작이 느림

위에 나열되지 않은 항목은 버그 신고를 참조하세요.

로그 파일

VMark는 문제 진단을 돕기 위해 로그 파일을 기록합니다. 로그에는 Rust 백엔드와 프론트엔드의 경고 및 오류가 포함됩니다.

로그 파일 위치

플랫폼	경로
macOS	~/Library/Logs/app.vmark/
Windows	%APPDATA%\app.vmark\logs\
Linux	~/.local/share/app.vmark/logs/

로그 수준

수준	기록 내용	프로덕션	개발
Error	실패, 충돌	예	예
Warn	복구 가능한 문제, 대체 처리	예	예
Info	주요 이벤트, 상태 변경	예	예
Debug	상세 추적 정보	아니요	예

로그 순환

• 최대 파일 크기: 5 MB
• 순환: 이전 로그 파일 1개 유지
• 오래된 로그는 자동으로 교체됩니다

버그 신고

버그를 신고할 때 다음 정보를 포함해 주세요:

1. VMark 버전 — 내비게이션 바 배지 또는 정보 대화상자에 표시됩니다
2. 운영 체제 — macOS 버전, Windows 빌드 또는 Linux 배포판
3. 재현 절차 — 문제가 발생하기 전에 수행한 작업
4. 로그 파일 — 관련 로그 항목을 첨부하거나 붙여넣으세요

로그 항목에는 타임스탬프가 찍혀 있고 모듈별로 태그가 지정됩니다(예: [HotExit], [MCP Bridge], [Export]). 이를 통해 관련 부분을 쉽게 찾을 수 있습니다.

관련 로그 찾기

1. 위 표를 참고하여 로그 디렉터리를 엽니다
2. 가장 최근의 .log 파일을 엽니다
3. 문제가 발생한 시간 부근의 ERROR 또는 WARN 항목을 검색합니다
4. 관련 행을 복사하여 버그 신고에 포함합니다

자주 발생하는 문제

Windows에서 앱 시작이 느림

VMark는 macOS에 최적화되어 있습니다. Windows에서는 WebView2 초기화로 인해 시작이 느릴 수 있습니다. 다음을 확인하세요:

• WebView2 Runtime이 최신 버전으로 업데이트되어 있는지
• 바이러스 백신 소프트웨어가 앱 데이터 디렉터리를 실시간 검사하고 있지 않은지

언어 변경 후 메뉴 바가 영어로 표시됨

설정에서 언어를 변경한 후에도 메뉴 바가 영어로 표시되면 VMark를 다시 시작하세요. 다음 실행 시 저장된 언어 설정으로 메뉴가 다시 구성됩니다.

터미널에서 CJK 문장 부호가 입력되지 않음

v0.6.5 이상에서 수정되었습니다. 최신 버전으로 업데이트하세요.

MCP 서버 연결 문제

MCP 서버가 시작되지 않거나 클라이언트가 연결되지 않을 수 있습니다.

• VMark가 실행 중인지 확인하세요 — MCP 서버는 앱이 열려 있을 때만 시작됩니다.
• 다른 프로세스가 동일한 포트를 사용하고 있지 않은지 확인하세요. MCP 서버는 클라이언트 검색을 위해 포트 파일을 작성합니다. 이전 세션의 오래된 포트 파일이 충돌을 일으킬 수 있습니다. VMark를 재시작하여 재생성하세요.
• 로그 파일에서 [MCP Bridge] 항목을 확인하여 연결 오류를 식별하세요.

키보드 단축키가 작동하지 않음

단축키가 다른 바인딩과 충돌하거나 사용자 지정된 경우 응답하지 않는 것처럼 보일 수 있습니다.

• 설정 (Mod + ,)을 열고 단축키 탭으로 이동하여 단축키가 재할당되었는지 확인하세요.
• 중복 바인딩을 찾으세요 — 두 작업이 동일한 키 조합을 공유하면 하나만 실행됩니다.
• macOS에서 일부 단축키는 시스템 수준 바인딩(예: Mission Control, Spotlight)과 충돌할 수 있습니다. 시스템 설정 > 키보드 > 키보드 단축키 를 확인하세요.

내보내기/인쇄 문제

PDF 내보내기가 중단되거나 불완전한 출력을 생성할 수 있습니다.

• 내보내기에서 이미지가 누락된 경우 이미지 경로가 문서에 상대적이고 파일이 디스크에 존재하는지 확인하세요. 절대 URL 및 원격 이미지는 접근 가능해야 합니다.
• 출력 디렉터리의 파일 권한을 확인하세요 — VMark는 내보낸 파일을 저장하려면 쓰기 액세스가 필요합니다.
• 큰 문서의 경우 내보내기에 시간이 더 걸릴 수 있습니다. 멈춘 것 같으면 로그 파일에서 [Export] 항목을 확인하세요.

파일이 열리지 않음

VMark가 파일 열기를 거부하거나 깨진 내용을 표시할 수 있습니다.

• 파일에 사용자 계정에 대한 읽기 권한이 있는지 확인하세요.
• VMark는 UTF-8로 인코딩된 Markdown을 기대합니다. 다른 인코딩(예: GB2312, Shift-JIS)의 파일은 올바르게 표시되지 않을 수 있습니다 — 먼저 UTF-8로 변환하세요.
• 파일이 다른 프로세스(예: 동기화 클라이언트 또는 백업 도구)에 의해 잠겨 있는 경우, 해당 프로세스를 종료하고 다시 시도하세요.

에디터 성능

매우 큰 파일이나 많은 열린 탭이 있으면 에디터가 느려질 수 있습니다.

• 사용하지 않는 탭을 닫아 메모리를 확보하세요 — 각 열린 탭은 자체 에디터 상태를 유지합니다.
• 매우 큰 문서(10,000줄 이상)는 입력 지연을 일으킬 수 있습니다. 더 작은 파일로 분할하는 것을 고려하세요.
• 필요하지 않으면 포커스 모드와 타자기 모드를 비활성화하세요. 추가 렌더링 오버헤드가 발생합니다.

AI 지니가 응답하지 않음

AI 지니는 작동하려면 구성된 AI 제공자가 필요합니다.

• 설정을 열고 AI 제공자(예: Ollama, OpenAI, Anthropic)가 유효한 모델 이름으로 구성되어 있는지 확인하세요.
• 제공자 CLI가 PATH에서 사용 가능해야 합니다. macOS에서 GUI 앱은 최소한의 PATH를 가집니다 — CLI가 Homebrew를 통해 설치된 경우 셸 프로필이 올바른 경로를 내보내는지 확인하세요.
• 모델 이름에 오타가 없는지 확인하세요. 잘못된 모델 이름은 자동으로 실패하거나 오류를 반환합니다.