문제 해결

아래 증상에서 시작하세요. 수동으로 저장소를 변경하기 전에 프로젝트 파일을 보존합니다.

Locus가 없거나 로드되지 않음

플러그인이 <Project>/Plugins/Locus/에 있고 Edit > Plugins에서 활성화되어 있는지 확인합니다.
패키지가 프로젝트의 정확한 Unreal Engine 마이너 버전과 일치하는지 확인합니다.
플러그인을 활성화하거나 교체한 후 Unreal Editor를 다시 시작합니다.
Window > Locus 또는 Ctrl+Shift+L을 시도합니다.
Unreal Output Log에서 LogLocus 카테고리와 플러그인 로드 오류를 검토합니다.

바이너리 패키지가 다른 Engine 마이너 버전을 대상으로 한다면 올바른 패키지로 교체하세요. 패키지 사이에서 개별 바이너리를 복사하지 마세요.

콘텐츠가 읽기 전용임

소스 컨트롤을 열고 파일이 관리되는지, 다른 사용자 또는 클라이언트가 체크아웃했는지, 오래되었는지, 제공자 연결이 끊겨 사용할 수 없는지 확인합니다. 깨끗한 관리 파일도 명시적으로 체크아웃할 때까지 읽기 전용입니다.

다른 클라이언트가 파일을 소유하거나, 작업 공간이 디포보다 뒤처져 있거나, 제공자가 안전한 상태를 보고할 수 없으면 체크아웃을 사용할 수 없을 수 있습니다. 프로젝트의 일반 소스 컨트롤 워크플로를 사용해 소유권 또는 리비전 상태를 해결하세요. 제공자에 다시 연결한 후 Unreal Source Control 또는 Locus를 새로 고칩니다. 체크아웃에 성공할 때까지 관리 콘텐츠는 읽기 전용입니다. 파일 시스템 권한을 변경해 보호를 우회하지 마세요.

개인 노트와 핀은 제공자에 의존하지 않아야 합니다. 사용할 수 없다면 프로젝트 Saved/Locus 저장소가 존재하고 쓰기 가능한지 확인하세요.

공급자가 구성되지 않은 경우 소스 제어 상태, 도구 설명, 지침, 체크아웃 또는 추가 대상으로 표시 UI가 없는 것은 일반적인 로컬 모드입니다. 구성되었지만 사용할 수 없는 공급자는 다르며 알려진 제어 콘텐츠를 보호합니다.

체크아웃 또는 추가 대상으로 표시 실패

Unreal의 공급자가 구성 및 연결되어 파일을 보고할 수 있는지 확인하세요. 생성 후 추가 대상으로 표시 요청이 실패하면 새로운 공유 노트가 디스크에 남습니다. 새로운 공유 핀 및 문서는 명시적으로 추가될 때까지 Untracked로 유지됩니다. 공유 핀 스냅샷에는 별도의 소스 제어 상태가 있습니다.

문서 이름을 변경하거나 이동할 수 없음

이름 변경과 이동에는 Locus 문서 작업 공간을 사용하세요. 콘텐츠 브라우저 항목은 권위 있는 이름 변경 표면이 아니라 프로젝션입니다. 이름을 변경할 수 있는 추적되지 않음 문서는 이름 변경 또는 F2, 이동 또는 유효한 기존 폴더로 드래그해 변경할 수 있습니다. Locus는 제공자 중립적인 소스 컨트롤 이동을 안전하게 수행할 수 없으므로 추가 대상으로 표시된 문서와 관리되는 문서에서는 이름 변경과 이동을 의도적으로 막습니다. 소스 컨트롤을 비활성화하거나 파일 시스템 권한을 변경해 우회하지 말고 추가 대상으로 표시하기 전에 문서를 정리하세요.

노트, 핀 또는 문서가 새로 고쳐지지 않음

활성 작업 공간의 재구축 또는 새로 고침 작업을 사용합니다. 외부 에디터에서 변경한 문서는 ProjectDocuments 아래에 유효한 UTF-8 .md 파일로 저장해야 합니다. 핀의 경우 현재 월드가 저장되어 있고 핀이 확인된 맵에 연결되어 있는지 확인합니다.

복구 가능

조치하기 전에 디스크의 기준 항목과 복구 사본을 검토합니다. 복원은 기준 항목을 복구 내용으로 바꾸고, 새 항목으로 복원은 둘 다 보존하며, 삭제는 복구 사본을 제거합니다. 확실하지 않다면 새 항목으로 복원하는 것을 우선하세요.

외부 충돌

외부 충돌은 Locus가 저장되지 않은 편집 내용을 보유한 동안 디스크 파일이 변경된 경우입니다. 강제로 덮어쓰지 마세요. 디스크 다시 로드, 로컬 작업을 새 항목으로 저장, 로컬 텍스트 복사 또는 가능한 경우 버전 비교 같은 제공된 작업을 사용합니다.

잘못되었거나 지원되지 않는 데이터

원본 파일을 보존하고 LogLocus 메시지를 확인합니다. 검증된 백업이 있고 형식을 이해하는 경우가 아니면 식별자나 소유권 필드를 직접 편집하지 마세요. 유효하지 않은 UTF-8 Markdown 파일은 가져오기에서 거부됩니다. 지원되지 않는 Markdown도 읽기 모드에서 완전히 표시되지 않더라도 소스로 유지됩니다.

참조가 없거나 오래되었습니다.

관련 작업공간을 새로 고치고 자산 핀, 노트, 문서 또는 Actor가 여전히 존재하는지 확인합니다. 이동되거나 삭제된 대상은 읽기 가능하지만 해결되지 않은 상태로 남아 있어 의도적으로 복구할 수 있습니다.

World Outliner에서 로드된 적합한 Actor를 정확히 하나만 편집 가능한 노트 또는 문서로 끌어서 Actor 참조를 작성하세요. 참조 삽입 및 @에는 없습니다. 레벨 인스턴스와 지원되지 않는 일시적 또는 미리보기 세계는 지원되지 않습니다.

핀을 사용할 수 없음

영구 핀에는 저장된 최상위 Editor 월드가 필요합니다. 맵을 저장하고 현재 맵으로 돌아가 배치를 다시 시도하세요. 모든 맵을 탐색하기 위해 핀 파일이 맵을 로드하거나 수정하지는 않습니다.

스냅샷 캡처 및 업데이트에는 사용 가능한 관점 Level Editor 뷰포트도 필요하며 PIE 중에는 사용할 수 없습니다.

문서가 없음

.md 파일이 <Project>/ProjectDocuments/ 아래에 있고 유효한 UTF-8을 사용하는지 확인합니다. 예약된 Content/ 하위 트리 밖의 경로는 Locus 문서 아래에 나타나며 Unreal 콘텐츠 브라우저로 프로젝션되지 않습니다. ProjectDocuments/Content/ 아래의 경로는 희소한 콘텐츠 브라우저 루트 아래에 나타나 대응하는 /Game 컨텍스트로 프로젝션됩니다. 외부 변경 후 문서를 새로 고칩니다. 관련 없는 /Game 폴더가 없는 것은 의도된 동작입니다. 트리는 Asset Registry 폴더가 아니라 인덱싱된 문서에서 만들어집니다. 문서는 외부 프로젝션 항목이지 UAsset이 아니라는 점도 기억하세요.

Markdown이 예상대로 렌더링되지 않음

지원되는 구문은 문서에서 확인합니다. 원시 HTML과 안전하지 않은 URL은 비활성 상태로 남고 원격 콘텐츠는 가져오지 않으며 브라우저와 동일한 Markdown 렌더링을 보장하지 않습니다. 권위 있는 소스가 온전한지 확인하려면 편집 모드로 전환하세요.

MCP 클라이언트가 연결되지 않거나 거부됨

Unreal Editor를 열어 둔 상태에서 Editor Preferences > Plugins > Locus > MCP Integration을 사용해 MCP 활성화가 켜져 있고 상태가 실행 중인지 확인합니다. 로컬 엔드포인트 또는 클라이언트 구성을 사용할 수 없다면 로컬 포트를 변경하거나 자격 증명을 재생성한 후 새 구성을 복사하세요.

복사하기 전에 일치하는 클라이언트 형식을 선택합니다. Claude Code와 Gemini CLI 등록 명령은 대화형 프롬프트가 아니라 일반 터미널에서 실행하세요. Gemini는 사용자 범위를 사용하므로 오래된 전역 locus 항목이 다른 프로젝트의 엔드포인트를 가리킬 수 있습니다. 현재 열려 있는 프로젝트의 새 구성으로 교체하세요. 복사한 명령이나 자격 증명을 지원 요청에 붙여 넣지 마세요.

활성 Locus 세션은 한 클라이언트만 소유할 수 있습니다. 이전 클라이언트를 닫거나 연결 해제하고 잠시 기다린 뒤 다시 시도하세요. 해당 클라이언트를 더 이상 사용하지 않을 때만 활성 클라이언트 재설정을 사용합니다. 변경 작업에는 변경 허용이 필요하고 개인 노트나 핀에는 개인 노트 및 핀 허용이 별도로 필요합니다. MCP 핀 작업은 지원되는 저장된 프로젝트 소유 /Game/... 월드 기준으로 제한됩니다.

전체 연결, 권한, 지원 도구 및 핀 컨텍스트 안내는 MCP 통합을 참조하세요.

문서 또는 의견이 열리지 않음

외부 링크는 운영 체제의 기본 브라우저를 사용합니다. 기본 HTTP/HTTPS 브라우저가 구성되어 있고 운영 체제가 URL 실행을 허용하는지 확인하세요. 실패해도 프로젝트 데이터는 변경되지 않습니다. MCP 통합에는 도움말 버튼이 있고 Locus에는 의견 보내기도 있습니다.