문제 해결
빠른 조회
자주 발생하는 문제와 해결 방법 위치:
| 증상 | 원인 가능성 | 확인할 곳 |
|---|---|---|
| MCP 클라이언트가 연결할 수 없음 | 오래된 포트 파일 또는 VMark가 실행 중이 아님 | MCP 서버 연결 문제 |
| 파일이 열리지 않거나 깨진 텍스트가 표시됨 | UTF-8이 아닌 인코딩 또는 격리 속성 | 파일이 열리지 않음 |
| AI 지니가 멈추거나 아무것도 반환하지 않음 | 제공자 잘못 구성 또는 CLI가 PATH에 없음 | AI 지니가 응답하지 않음 |
| 키보드 단축키가 아무것도 하지 않음 | 설정에서 재할당되었거나 시스템 재정의 | 키보드 단축키가 작동하지 않음 |
| 큰 파일에서 에디터 느림 | 탭당 메모리 + 10,000행 이상 입력 지연 | 에디터 성능 |
| 언어 변경 후에도 메뉴가 영어로 | 시작 시 메뉴 재구성 | 메뉴 바가 영어로 표시됨 |
| PDF 내보내기 불완전 | 이미지 경로 또는 쓰기 권한 | 내보내기/인쇄 문제 |
| Windows에서 시작이 느림 | WebView2 + 안티바이러스 검사 | Windows에서 앱 시작이 느림 |
Cmd + R / Ctrl + R이 아무것도 하지 않음 | 설계상 새로 고침이 차단됨 | 새로 고침이 차단됨 |
| 파일을 더블클릭했더니 실행 중인 VMark에서 열림 | Windows와 Linux의 단일 인스턴스 전달 | Windows와 Linux에서는 한 번에 하나의 VMark만 실행됨 |
| Linux에서 빈 창 | WebKitGTK DMABUF 렌더러 | Linux에서 빈 창이 표시됨 |
macOS에서 곧은 따옴표와 --가 그대로 남음 | VMark에서는 시스템 스마트 대치가 꺼져 있음 | macOS의 스마트 따옴표와 대시 |
| 활성 상태 보기에서 VMark가 전혀 "낮잠"을 자지 않음 | AI 어시스턴트가 계속 작동하도록 App Nap이 비활성화됨 | 백그라운드에서도 VMark가 깨어 있음 |
최근 워크스페이스를 열 때 폴더 선택 대화상자가 열리거나 오류에 forbidden path가 표시됨 | 폴더가 VMark가 읽을 수 있는 범위 밖에 있음 | 폴더 접근과 forbidden path 오류 |
위에 나열되지 않은 항목은 버그 신고를 참조하세요.
로그 파일
VMark는 문제 진단을 돕기 위해 로그 파일을 기록합니다. 로그에는 Rust 백엔드와 프론트엔드의 경고 및 오류가 포함됩니다.
로그 파일 위치
| 플랫폼 | 경로 |
|---|---|
| macOS | ~/Library/Logs/app.vmark/ |
| Windows | %LOCALAPPDATA%\app.vmark\logs\ |
| Linux | ~/.local/share/app.vmark/logs/ |
로그 수준
| 수준 | 기록 내용 | 프로덕션 | 개발 |
|---|---|---|---|
| Error | 실패, 충돌 | 예 | 예 |
| Warn | 복구 가능한 문제, 대체 처리 | 예 | 예 |
| Info | 주요 이벤트, 상태 변경 | 예 | 예 |
| Debug | 상세 추적 정보 | 아니요 | 예 |
로그 순환
- 최대 파일 크기: 5 MB
- 순환: 이전 로그 파일 1개 유지
- 오래된 로그는 자동으로 교체됩니다
버그 신고
버그를 신고할 때 다음 정보를 포함해 주세요:
- VMark 버전 — 내비게이션 바 배지 또는 정보 대화상자에 표시됩니다
- 운영 체제 — macOS 버전, Windows 빌드 또는 Linux 배포판
- 재현 절차 — 문제가 발생하기 전에 수행한 작업
- 로그 파일 — 관련 로그 항목을 첨부하거나 붙여넣으세요
로그 항목에는 타임스탬프가 찍혀 있고 모듈별로 태그가 지정됩니다(예: [HotExit], [MCP Bridge], [Export]). 이를 통해 관련 부분을 쉽게 찾을 수 있습니다.
관련 로그 찾기
- 위 표를 참고하여 로그 디렉터리를 엽니다
- 가장 최근의
.log파일을 엽니다 - 문제가 발생한 시간 부근의
ERROR또는WARN항목을 검색합니다 - 관련 행을 복사하여 버그 신고에 포함합니다
자주 발생하는 문제
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 파일만 엽니다. (바이트 순서 표시로) UTF-16 또는 UTF-32임이 표시된 파일은 열 때 거부되며 토스트가 나타납니다: "경로은(는) 인코딩(으)로 인코딩되어 있습니다. VMark는 UTF-8 파일만 열 수 있습니다. 다른 편집기에서 UTF-8로 저장한 뒤 다시 여세요." 그 밖의 레거시 인코딩(GB2312, Shift-JIS)에는 표시가 없어서 열리기는 하지만 글자가 깨져 보일 수 있습니다 — 먼저 UTF-8로 변환하세요.
- 바이트 순서 표시로 시작하는 UTF-8 파일은 그 표시를 유지합니다: VMark는 열기와 저장 과정에서 BOM을 보존합니다.
- 파일이 다른 프로세스(예: 동기화 클라이언트 또는 백업 도구)에 의해 잠겨 있는 경우, 해당 프로세스를 종료하고 다시 시도하세요.
- macOS: VMark가 실행 중일 때 다운로드한 파일을 더블클릭해도 아무 일도 일어나지 않습니다. 일부 앱이 저장한 파일에는 다운로드 격리 속성(
com.apple.quarantine)이 붙으며, macOS는 이미 실행 중인 앱에서 그런 파일을 열라는 요청을 조용히 무시할 수 있습니다. 워크스페이스를 열면 VMark는 워크스페이스 폴더와 그 바로 안에 있는, VMark가 열 수 있는 파일에서 이 속성을 제거합니다(하위 폴더는 건드리지 않음) — 설정 → 고급 → macOS 의 작업 공간을 열 때 다운로드 격리 해제 설정이며, 기본적으로 켜져 있습니다. 그 밖의 파일은 파일 → 파일 열기 를 사용하거나, 터미널에서xattr -d com.apple.quarantine <file>을 실행하세요.
폴더 접근과 forbidden path 오류
홈 폴더와 마운트된 볼륨 밖 — Windows에서는 C:\부터 F:\까지의 드라이브 밖 — 에서는 VMark가 접근 권한을 받은 것만 읽습니다. 자세한 내용은 VMark가 디스크에서 읽을 수 있는 범위를 참조하세요.
- 최근 워크스페이스를 선택하면 폴더 선택 대화상자가 열립니다. VMark는 사용자가 이전에 그 폴더를 선택했는지 확인할 수 없고, 그곳을 읽을 다른 방법도 없습니다. 대화상자는 해당 폴더를 연 상태로 나타납니다. 열기를 클릭해 확인하면 그때부터 VMark가 그 폴더를 기억합니다. 취소하면 아무것도 열리지 않습니다.
- AI 어시스턴트가 폴더를 열어 달라고 요청하면 한 단계가 더 필요합니다. 요청을 승인하면 VMark가 같은 대화상자를 표시합니다. 그곳에서 폴더를 선택한 뒤 어시스턴트가 다시 시도하게 하세요.
- 오류에
forbidden path가 표시되거나 이미지가 보이지 않습니다. 그 파일은 VMark가 읽을 수 있는 어떤 위치에도 없습니다 — 대개 단독으로 연 문서 옆에 있는 이미지입니다. **파일 → 워크스페이스 열기...**로 문서의 폴더를 열어 VMark에 폴더 전체에 대한 접근 권한을 주세요.
에디터 성능
매우 큰 파일이나 많은 열린 탭이 있으면 에디터가 느려질 수 있습니다.
- 사용하지 않는 탭을 닫아 메모리를 확보하세요 — 각 열린 탭은 자체 에디터 상태를 유지합니다.
- 매우 큰 문서(10,000줄 이상)는 입력 지연을 일으킬 수 있습니다. 더 작은 파일로 분할하는 것을 고려하세요.
- 필요하지 않으면 포커스 모드와 타자기 모드를 비활성화하세요. 추가 렌더링 오버헤드가 발생합니다.
AI 지니가 응답하지 않음
AI 지니는 작동하려면 구성된 AI 제공자가 필요합니다.
- 설정을 열고 AI 제공자(예: Ollama, OpenAI, Anthropic)가 유효한 모델 이름으로 구성되어 있는지 확인하세요.
- 제공자 CLI가 PATH에서 사용 가능해야 합니다. macOS에서 GUI 앱은 최소한의 PATH를 가집니다 — CLI가 Homebrew를 통해 설치된 경우 셸 프로필이 올바른 경로를 내보내는지 확인하세요.
- 모델 이름에 오타가 없는지 확인하세요. 잘못된 모델 이름은 자동으로 실패하거나 오류를 반환합니다.
새로 고침이 차단됨
Cmd + R, Ctrl + R, Ctrl + Shift + R은 의도적으로 아무것도 하지 않습니다. 웹뷰를 새로 고치면 열려 있는 모든 에디터와 그 실행 취소 기록, 저장되지 않은 상태가 모두 사라지므로, VMark는 이 단축키와 페이지 언로드 경로, 웹뷰 자체의 컨텍스트 메뉴를 차단합니다. 예외는 두 가지입니다: 통합 터미널에 포커스가 있으면 Ctrl + R이 셸에 전달되고(reverse-i-search), F5는 소스 미리 보기 단축키이므로 절대 차단되지 않습니다. 개발 빌드는 차단하는 대신 저장되지 않은 문서에 대해 경고만 합니다.
Windows와 Linux에서는 한 번에 하나의 VMark만 실행됨
파일을 더블클릭하거나 런처에서 VMark를 다시 실행하면, 두 번째 사본을 시작하는 대신 이미 실행 중인 VMark에 파일을 넘기고 창을 앞으로 가져옵니다. 두 번째 프로세스는 첫 번째 프로세스의 앱 데이터, 세션, 창 저장소를 공유하게 되고, 둘이 서로의 상태를 덮어쓰게 됩니다 — #1330의 데이터 손실 원인이 바로 이것입니다. macOS는 운영 체제를 통해 항상 이렇게 동작해 왔습니다. 개발(tauri dev) 빌드는 자체 식별자를 사용하므로 다른 앱으로 취급됩니다.
Windows에서 이미 실행 중인 VMark가 응답하지 않아 전달을 더 이상 받을 수 없으면, 새 실행은 그 옆에 두 번째 사본을 시작하지 않습니다. 대신 메시지를 표시합니다. 작업 관리자를 열어 모든 VMark 프로세스를 종료한 다음 VMark를 다시 시작하세요(#1527).
Linux에서는 이 기능이 D-Bus 세션 버스에 의존합니다. 사용할 수 있는 DBUS_SESSION_BUS_ADDRESS가 없는 세션에서도 VMark는 시작되지만 이 보호 장치 없이 시작되며 — 다시 실행하면 위에서 설명한 위험을 안고 두 번째 사본이 시작됩니다 — 로그에 보호 장치가 꺼져 있다고 기록됩니다. 데스크톱 세션이나 이 변수가 설정된 셸에서 실행하세요.
Linux에서 빈 창이 표시됨
일부 AMD / Mesa / WebKitGTK 조합(보고된 사례는 KDE Plasma 6을 사용하는 Arch, #1058)에서는 WebKitGTK의 DMABUF 렌더러가 실패하여 콘텐츠 영역이 빈 채로 남습니다. VMark는 웹뷰가 시작되기 전에 WEBKIT_DISABLE_DMABUF_RENDERER=1을 설정하여 이런 일이 생기지 않게 합니다. DMABUF 렌더러를 다시 사용하려면 WEBKIT_DISABLE_DMABUF_RENDERER=0으로 실행하세요 — VMark는 이 변수가 설정되어 있지 않을 때만 설정합니다.
중국어 입력기를 켠 상태에서 단축키가 문자를 입력함
수정되었습니다. 중국어 문장 부호가 켜져 있으면 입력기가 문장 부호 키를 바꿔 씁니다 — 백틱 키는 ·를, 대괄호는 【】를 입력합니다 — 그리고 앱이 키가 눌렸다는 사실을 알기 전에 그 문자를 확정합니다. 그래서 예전에는 Ctrl + `가 터미널을 전환하면서 문서에 엉뚱한 ·를 남겨, 깨끗한 파일을 편집된 것으로 표시했습니다.
이제 VMark는 키 입력이 아니라 문자 삽입 자체를 거부하므로, 명령 조합키는 아무것도 입력하지 않습니다. 일반적인 중국어 입력, 데드 키(Option + e), 유럽 키보드의 AltGr 문자는 영향을 받지 않습니다 — Ctrl이나 Cmd를 누른 상태에서 들어오는 삽입만 거부되며, "이 문자를 입력하라"는 의미의 VMark 조합키는 없습니다.
단축키 때문에 여전히 엉뚱한 문자가 입력된다면, 입력기 이름과 정확한 조합키를 함께 신고해 주세요.
macOS의 스마트 따옴표와 대시
Mac에서 스마트 따옴표 및 대시 사용 이 켜져 있어도 VMark에서 입력한 --나 "는 그대로 유지됩니다. 그렇지 않으면 시스템이 에디터 밑에서 텍스트를 바꿔 쓰기 때문입니다 — Mermaid 블록의 -->가 —>로 바뀌었습니다. 그래서 VMark는 자기 프로세스에 한해서만 자동 대시, 따옴표, 마침표 대치를 끕니다. 다른 앱은 영향을 받지 않으며, 입력기와 사용자 자신의 텍스트 대치도 마찬가지입니다. VMark 안에서 인쇄용 따옴표를 쓰려면 CJK 포매터의 스마트 따옴표 규칙이나 따옴표 스타일 토글(Shift + Mod + ')을 사용하세요.
백그라운드에서도 VMark가 깨어 있음 (App Nap)
macOS에서 VMark는 실행되는 동안 App Nap에서 제외되므로, 창이 숨겨져 있어도 활성 상태 보기에는 VMark가 한 번도 낮잠을 자지 않는 것으로 표시됩니다. App Nap은 창을 앞으로 가져올 때까지 웹뷰를 — 그리고 그와 함께 모든 AI 어시스턴트(MCP) 요청을 — 멈추게 합니다. 깨어 있기 때문에 다른 앱을 사용하는 동안에도 어시스턴트가 계속 작업할 수 있습니다. 유휴 상태일 때 시스템은 여전히 잠자기에 들어갈 수 있으며, VMark는 낮잠 상태로 전환하지 말아 달라고 요청할 뿐입니다.