Cursor에서 Biome 포맷팅이 동작하지 않는 현상 디버깅
진단하기
추석 이후로 Cursor에서 Biome 자동 포맷팅이 갑자기 동작하지 않는 문제가 발생했어요. 코드를 저장해도 포맷팅이 전혀 적용되지 않아서 개발 생산성에 큰 지장이 생겼어요.
Output 로그에서 확인한 에러
Biome extension의 Output 로그를 확인해보니 플러그인 버전에 따라 다른 에러가 교차로 발생하고 있었어요:
- 최신 플러그인 사용 시:
Cannot unshim Biome binary at "/Users/chanhyuk.park/Desktop/toss/toss-frontend/biome"
because it is version 1.x.x. Please update to version 2 or higher.- 구버전 플러그인 사용 시:
Unable to find the Biome binary.이 에러 메시지들을 통해 Biome 플러그인과 바이너리 간의 버전 불일치 문제임을 추정할 수 있었어요.
재현하기
시도한 해결 방법들:
- Cursor 재시작 (여러 번) → 해결 안됨
- 구글링 → 유의미한 자료를 찾기 어려움
- GitHub 이슈 검색 → 비슷한 사례 찾기
- 플러그인 수동 설치 시도
- 플러그인이 자동 업데이트되었을 것으로 추정
- vsix 파일로 수동 설치 시도
- 동료에게 문의
- 민호님께 사용 중인 플러그인 버전 확인
- 민호님은 v3.2.0을 마켓플레이스에서 설치해서 정상 동작 중
원인 파악:
- 모노레포에는 Biome v1 바이너리가 존재해요
- Cursor의 Biome 플러그인은 v2 이상을 기대하는 상태로 자동 업데이트되었어요
- 결과적으로 플러그인 ↔ 바이너리 버전 불일치로 포맷팅과 LSP가 모두 실패한 거예요
수정하기
다음 두 단계 조합으로 문제를 해결했어요:
- 컴퓨터 재부팅
- Biome extension을 마켓플레이스에서 v3.2.0으로 재설치
처음에는 Cursor만 여러 번 재시작했을 때는 해결되지 않았고, 재부팅만 했을 때도 해결되지 않았어요. 하지만 재부팅 + 플러그인 재설치를 함께 수행하니 정상적으로 동작했어요!
- 컴퓨터 완전히 재부팅
- Cursor 실행
- Extensions에서 Biome 플러그인 제거
- Marketplace에서 Biome v3.2.0 새로 설치
- 파일 저장 시 포맷팅 정상 동작 확인 ✅
재발방지하기
플러그인 자동 업데이트 주의
VS Code 계열 에디터(Cursor 포함)는 플러그인을 자동으로 업데이트하는 경우가 많아요. 특히 Biome처럼 로컬 바이너리와 연동되는 플러그인의 경우, 플러그인 버전과 바이너리 버전의 호환성이 깨질 수 있어요. 중요한 도구의 플러그인은 자동 업데이트를 비활성화하거나, 업데이트 후에는 반드시 동작을 확인해야 해요.
모노레포 환경에서 도구 버전 관리
모노레포에서 Biome v1을 사용하는데 플러그인은 v2를 기대하는 상황처럼, 팀 전체가 사용하는 도구의 버전을 명확히 관리해야 해요. package.json이나 README에 권장 플러그인 버전을 명시하고, 새로운 팀원이나 업데이트 후 문제가 생겼을 때 빠르게 대응할 수 있도록 문서화하는 것이 중요해요.
재부팅의 힘을 믿기
"재부팅 해보시죠.."라는 민호님의 조언처럼, 개발 도구 관련 문제는 의외로 재부팅으로 해결되는 경우가 많아요. 특히 에디터나 플러그인 관련 이슈는 프로세스나 캐시 문제일 수 있으므로, 복잡한 디버깅을 시도하기 전에 먼저 재부팅을 시도해보는 것도 좋은 전략이에요.
동료에게 버전 확인하기
같은 코드베이스에서 작업하는 동료에게 "혹시 잘 되시나요?", "몇 버전 쓰시나요?"라고 물어보는 것이 의외로 빠른 해결책이 될 수 있어요. 다른 사람은 정상 동작한다면 로컬 환경 문제일 가능성이 높고, 사용 중인 버전 정보를 통해 문제를 빠르게 좁혀나갈 수 있어요.
Output 로그 확인 필수
포맷팅이 안 된다고 바로 포기하지 말고, 플러그인의 Output 로그를 확인하는 습관이 중요해요. 이 경우처럼 에러 메시지가 명확히 원인을 알려주는 경우가 많아요. VS Code/Cursor에서 View → Output을 열고 해당 플러그인을 선택하면 상세한 로그를 볼 수 있어요.