문제 해결 & 자주 묻는 질문#
프로필 연결 테스트 시 “연결 실패”#
증상: 연결 테스트 및 자동탐색을 클릭하면 “Harang contacts: 연결 실패 - …” 알림이 뜹니다.
원인: 대개 다음 중 하나입니다:
서버 URL이 잘못되었거나, 접속할 수 없거나,
https://스킴이 빠져 있습니다.사용자명 또는 비밀번호가 틀렸습니다.
서버가 표준 CardDAV 탐색 절차(
current-user-principal→addressbook-home-set)를 지원하지 않으면서, URL이 주소록 컬렉션을 직접 가리키고 있지도 않습니다.
해결: 자격 증명을 다시 확인하고, 탐색이 계속 실패한다면 Server URL을 서버 루트 대신 주소록 컬렉션 URL로 직접 지정해보세요(예: Nextcloud의 https://<host>/remote.php/dav/addressbooks/users/<user>/contacts/).
칩이 흐릿하고 점선 테두리로 보임 (“미해석”)#
증상: {{hrcard:...}} 칩이 일반적인 칩 대신 낮은 불투명도와 점선 테두리로 표시됩니다.
원인: 플러그인이 현재 캐시에서 일치하는 연락처를 찾지 못했습니다. 참조된 연락처가 서버에서 삭제됐거나, 노트를 작성한 이후로 로컬 캐시가 아직 새로고침되지 않았거나, 실제로 존재하지 않는 프로필 id/UID로 참조를 손으로 직접 입력한 경우, 또는 프로필 식별자 부분이 표시 이름에서 내부 id로 바뀌기 전에 삽입된 참조가 노트에 남아 있는 경우에 발생합니다 - 이름 기반 대체 해석 경로가 없으므로, 그런 참조는 {{hrcard: 자동완성으로 삭제 후 다시 삽입해야 합니다(아키텍처 참고 - 이 문법은 표시 이름이 아니라 프로필 id + CardDAV UID를 저장하므로, 손으로 입력한 참조나 오래된 참조는 정확한 현재 id가 있어야만 해석됩니다).
해결: 주소록 새로고침 명령을 실행하거나(또는 설정에서 새로고침을 클릭) 노트를 다시 여세요. 새로고침 후에도 칩이 계속 미해석 상태라면, 손으로 입력하지 말고 그 칩을 지운 뒤 {{hrcard: 자동완성 팝업을 통해 다시 삽입하세요.
설치 후 플러그인이 보이지 않음#
해결: main.js, manifest.json, styles.css가 (하위 폴더가 아니라) <vault>/.obsidian/plugins/harang-contacts/ 바로 안에 있는지, 설정 → 커뮤니티 플러그인에서 플러그인이 활성화되어 있는지, Obsidian이 1.13.4 이상인지(사전 준비 사항 참고) 확인하세요. 파일을 설치·갱신한 뒤에는 Obsidian을 완전히 재시작하세요.
git pull 이후에도 플러그인이 갱신되지 않음#
증상: 최신 소스 변경 사항을 pull 했는데도, Obsidian은 여전히 이전 버전처럼 동작합니다.
원인: 소스로 설치한 경우 명시적인 재빌드와 수동 복사 과정이 필요합니다 — 새 소스를 pull하는 것만으로는 Obsidian이 실제로 불러오는 파일이 갱신되지 않습니다.
해결: 설치의 방법 3에 나온 전체 갱신 절차를 실행하세요:
git pull
npm install
npm run build
그런 다음 새로 빌드된 main.js(그리고 바뀌었다면 manifest.json/styles.css도)를 <vault>/.obsidian/plugins/harang-contacts/에 다시 복사하고 Obsidian을 재시작하세요.