Stuck Indexing Cursor IDE 에러 해결법

Cursor 쓰다 보면 코드베이스 인덱싱이 0%에서 멈춰서 안 움직이는 경우가 있습니다. 분명 유료 결제까지 하고 쓰는데 폴더 전체를 못 읽으니 파일 몇 개만 갖고 답변하는 상황이 생기구요. 이럴 때 터미널 붙들고 씨름하지 말고 몇 가지만 확인하면 바로 해결됩니다.

커서는 프로젝트 전체 맥락을 읽어야 진가를 발휘하는 도구인데 인덱싱이 멈추면 그냥 일반 챗봇이랑 다를 게 없어집니다. 회사에서 API 비용을 내든 개인 구독료를 내든 돈값 못하는 느낌이 들어서 짜증이 나기 마련이구요. 윈도우와 맥 환경에서 자주 발생하는 커서 인덱싱 오류와 해결법을 정리해 봤습니다.

Step 1: Cursor IDE Indexing Stuck 멈춤 해결하기

가장 자주 발생하는 현상은 커서가 프로젝트 폴더 내의 특정 무거운 폴더나 대용량 파일을 전부 읽으려고 하다가 메모리 한계로 멈춰버리는 문제입니다. node_modules나 build 폴더, 혹은 이미지/데이터셋 폴더가 잡혀 있으면 인덱싱이 끝없이 돌게 되구요.

이럴 때는 설정(톱니바퀴 아이콘)으로 들어가서 Features 메뉴의 Codebase Indexing 항목을 확인해야 합니다. 그 아래에 있는 Exclude Files 설정에 빌드 폴더와 라이브러리 경로가 제대로 등록되어 있는지 봐야 하구요. 아래 경로들을 추가해 주는 것만으로도 막혔던 인덱싱이 바로 진행되는 경우가 많습니다.

만약 이렇게 제외 설정을 넣었는데도 계속 0%에서 머물러 있다면 기존에 쌓인 인덱스 캐시 데이터가 깨진 상태일 가능성이 높습니다. 이때는 커서가 관리하는 로컬 캐시 폴더를 강제로 밀어버려야 하구요. 윈도우의 경우 아래 경로의 workspaceStorage 폴더로 이동해서 해당 프로젝트의 캐시 데이터를 지워주면 해결됩니다.

위 폴더를 통째로 지우고 커서를 재시작하면 프로젝트 폴더를 처음부터 깨끗하게 다시 읽기 시작하면서 인덱싱 바가 쭉쭉 올라가는 것을 볼 수 있습니다.

Step 2: Cursor Composer Write Permission 쓰기 권한 에러 풀기

두 번째는 Composer 모드에서 에이전트가 코드를 알아서 고치다가 갑자기 파일 수정 권한이 없다면서 진행을 멈추는 에러입니다. 특히 git 관련 작업을 병행하거나 시스템 보호 영역 내에 프로젝트가 있는 경우 발생하구요.

원인은 커서 프로세스가 OS의 관리자 권한을 얻지 못했거나, 파일 제어권이 다른 프로세스에 묶여 있는 탓입니다. 터미널 창을 열어서 먼저 git 프로세스가 락을 잡고 있는지 확인하고 락 파일을 강제로 날려야 합니다. 아래 명령어로 레포지토리의 git lock을 지워주면 해결되구요.

이래도 해결되지 않는다면 커서 에디터를 완전히 종료한 뒤 윈도우 시작 메뉴에서 마우스 우클릭을 해 관리자 권한으로 실행하기로 다시 켜는 것이 제일 확실합니다. 특히 WSL 환경을 연동해서 쓰거나 리눅스 컨테이너와 볼륨을 공유할 때 파일 권한 충돌이 잦으니 작업 디렉토리의 소유권을 점검해보는 것도 괜찮습니다.

Step 3: Cursor API Key Validation Failed 연동 오류 해결

세 번째는 유료 구독 대신 개인 OpenAI나 Anthropic API 키를 등록해서 쓰는데 자꾸 키 검증에 실패했다는 경고창이 뜨는 현상입니다. 키는 분명히 맞는데 연동이 안 되니 답답할 수밖에 없구요.

대부분은 프록시(Proxy) 설정이나 사내 네트워크 방화벽이 커서의 외부 API 호출을 차단하고 있어서 생기는 현상입니다. 혹은 API 제공업체 콘솔에 등록된 결제 카드가 만료되어 일시적으로 API 사용 제한이 걸렸을 수도 있구요. API 키 검증을 통과하려면 커서의 네트워크 설정을 점검해야 합니다.

커서의 네트워크 설정 탭에서 'Disable GPU' 옵션을 켜보거나, 시스템 환경 변수에 HTTP_PROXY가 등록되어 있는지 체크하는 게 좋구요. 사내망이라면 프록시 주소를 커서 설정에 명시해 주어야 정상적으로 연동이 됩니다. API 제공업체 계정 페이지에서 사용량 제한(Usage Limit)에 걸렸는지도 반드시 확인해야 하구요. 계정에 크레딧 잔액이 없는 경우에도 같은 에러가 나니까요.

직접 써보면서 느낀 건 커서가 엄청 편하긴 한데 가끔 이렇게 먹통이 될 때 에러 로그를 직접 확인하지 않으면 삽질을 길게 하게 된다는 점이구요. 위 세 가지만 순서대로 점검해도 웬만한 먹통 현상은 다 풀리니 무작정 재설치부터 하지 말고 설정 예외 처리와 로컬 캐시 삭제부터 차근차근 시도해 보는 것을 추천합니다.