문제 해결 & FAQ#
“Immich 서버 주소와 API 키를 먼저 설정에서 입력해주세요.”#
갤러리, 업로드, 삭제 동작을 시도했는데 사용 중인 프로필에 서버 주소와 API 키가 아직 모두 입력되지 않았거나, 프로필이 하나도 설정되어 있지 않은 경우 이 메시지가 표시됩니다. Settings → Harang Immich에서 활성 프로필의 두 항목을 모두 입력하거나(또는 프로필을 추가하고) 다시 시도하세요.
“에셋 목록 조회 실패”, “썸네일 조회 실패”, “원본 이미지 조회 실패” (HTTP 상태 코드 포함)#
이는 요청이 Immich 서버까지는 도달했지만 서버가 오류를 반환했다는 뜻입니다. 흔한 원인은 다음과 같습니다:
API 키가 잘못되었거나 만료되었거나 Immich에서 취소된 경우.
서버 주소가 잘못된 경우 (
https://가 빠졌는지, 끝에 불필요한 경로가 붙어있는지 확인하세요).선택한 앨범이 더 이상 존재하지 않는 경우 (설정 탭을 다시 열어 앨범 드롭다운을 새로고침하거나
(전체 사진)을 선택하세요).
“업로드 실패” / “업로드 응답에 asset id가 없습니다”#
업로드 요청이 서버 쪽에서 실패했거나(Immich 서버 로그의 상태 코드를 확인하세요) Immich가 예상된 asset ID 없이 응답한 경우입니다. 서버 주소/API 키가 올바른지, 선택한 앨범에 업로드할 권한이 있는 계정인지 확인하세요.
노트에서 이미지가 깨진/오류 표시로 나타나는 경우#
이는 노트에 유효한 Harang Immich 링크가 있지만 해당 에셋의 썸네일을 가져오는 데 실패했다는 뜻입니다 (예: Obsidian 밖에서 Immich 서버에서 직접 에셋을 삭제한 경우). 깨진 이미지 위에 마우스를 올리면 원인이 되는 오류 메시지를 볼 수 있습니다.
이미지에서 “프로필을 찾을 수 없음” 오류가 표시되는 경우#
링크에 담긴 프로필 이름이 Settings → Harang Immich에 현재 있는 어떤 프로필과도 일치하지 않는 경우입니다. 다음 둘 중 하나가 원인입니다:
그 프로필이 삭제된 경우입니다. 이 이미지들이 다시 동작하게 하려면 같은 서버로, 정확히 같은 이름으로 프로필을 다시 추가하세요.
그 프로필의 이름이 바뀐 경우입니다. 링크는 여전히 예전 이름을 찾고 있습니다. 프로필 이름을 원래 부르던 이름으로 되돌리면 이번 이름 변경 때문에 깨진 이미지들이 모두 복구됩니다.
프로필이 삭제되거나, 링크가 가리키던 이름에서 다른 이름으로 바뀌고 나면 원래 링크가 가리키던 대상을 복구할 방법은 없습니다 — 이름 자체가 링크가 그 프로필을 참조하는 유일한 수단이기 때문입니다.
이미지가 아예 이미지로 렌더링되지 않는 경우#
Harang Immich는 자체 전용 링크 문법만 렌더링합니다 — 일반 마크다운 이미지 문법()은 이 플러그인의 영향을 받지 않습니다. 링크가 정확히 ![immich:프로필 이름/ASSET_ID] 또는 ![immich:프로필 이름/ASSET_ID|alt text] 형태인지 확인하세요 (프로필 이름/ 부분이 없는 이전 링크도 유효합니다, 사용법 참고). 이 문법은 보통 자동으로 삽입되며, 직접 입력했다면 불필요한 공백이나 괄호 같은 오타가 없는지 다시 확인하세요.
캐시가 계속 늘어나요 / 공간을 확보하고 싶어요#
썸네일은 매번 볼 때마다 Immich에서 다시 내려받지 않도록 로컬에 캐시됩니다. Settings → Harang Immich를 열어 Cache management 아래의 Clear cache를 사용하세요. 이는 로컬 캐시 파일만 삭제하며 Immich 서버의 데이터는 전혀 삭제하지 않습니다.
모바일에서만 이미지 로드가 실패하는 경우#
Harang Immich는 자체 호스팅 Immich 서버와 통신할 때 Obsidian Mobile에 영향을 줄 수 있는 CORS 문제를 피하기 위해 일부러 Obsidian의 requestUrl API를 사용합니다. 그런데도 모바일에서만 이미지 로드가 실패한다면, 플러그인과 무관하게 모바일 기기가 실제로 Immich 서버 주소에 접근할 수 있는지 확인하세요 (예: VPN이 필요하거나 같은 로컬 네트워크에 있어야 할 수 있습니다).
노트를 삭제해도 이미지 처리 여부를 묻지 않는 경우#
삭제 확인 안내창은 노트가 삭제/이름변경/편집되는 시점에 실제로 하나 이상의 Harang Immich 링크를 참조하고 있던 경우에만 나타납니다. 일반 마크다운 이미지만 있거나 이미지가 전혀 없는 노트에서는 나타나지 않습니다.