Claude Code 업데이트 오류 상황 및 해결 방법

결론부터 쓰자면 Claude Code가 최신 버전으로 업데이트되지 않는 상황이 발생했고 아래 명령으로 간단히 해결했다.

claude install

따로 신경 안 써도 자동으로 최신 버전으로 업데이트되고 있을 거라 생각했는데 꽤 오래전부터 업데이트가 안 되고 있었다. 방금 전까지 사용하던 버전이 '2.0.30'이었는데 npm 버전 기록 페이지를 봤더니 대략 두 달 전 버전이었다. 비싼 돈 내고 MAX 플랜을 쓰고 있는데 민망하고 당황스러웠다.

2025년 12월 24일 현재, 최신 버전은 'v2.0.76'이다. 위 이미지와 같이 전에는 캐릭터가 주황색이었는데 아래와 같이 파란색으로 바뀐 것이 가장 먼저 눈에 띄었다. 아마 겨울 초입에 바뀌지 않았을까 싶다.

다시 업데이트 오류 상황으로 돌아가자면 Claude Code 사용 중에 우하단에 업데이트에 실패했다는 메시지가 잠깐 떴다가 사라졌다. 수동으로 업데이트해야겠다고 생각하고 Claude Code를 종료하고 터미널에서 아래와 같이 입력했다.

claude update

path 설정이 제대로 되지 않았다는 오류가 떠서 같이 표시된 가이드에 따라 path 설정을 하고 새 터미널을 띄웠다. 다시 'claude update' 명령을 실행했는데 이번엔 다른 오류가 떴다.

반응형

% claude update                                          
Current version: 2.0.30
Checking for updates...

Warning: Running native installation but config install method is 'unknown'
Fix: Run claude install to update configuration
Failed to check for updates

config install method가 uknown이라는데 구글링 하려다 Claude IDE를 띄우고 복사해서 그대로 채팅창에 타이핑했다.

시키는 대로 'claude install', 'claude update'를 실행했더니 바로 최신 버전으로 업데이트에 성공했다. 기억이 확실치 않은데 'claude install'만으로 업데이트까지 진행됐던 것 같다. 이후 이어진 claude와의 대화를 통해 '~/.claude.json' 파일에 아래와 같이 installMethod 필드가 있는 것을 확인했다.

{
  "numStartups": 24,
  "installMethod": "native",
  "autoUpdates": false,
  "tipsHistory": {
  ...

이 값이 지금은 'claude install' 명령으로 native로 고쳐졌는데 전에는 unknown이었다는 거다. 이 오류가 발생하는 원인은 여럿인데 대략 두 가지 원인 중 하나인 듯하다. 먼저 업데이트를 너무 오랜만에 한 경우다. 예전 버전의 Claude Code는 install method를 설정 파일에 기록하지 않았을 수 있는데 이후 업데이트 로직이 추가되면서 이 필드를 확인하면서 문제가 발생한 것이다. 두 번째로 예상되는 원인은 npm 설치와 Homebrew 설치를 반복하면서 설정이 꼬인 것이다. 내 경우는 어쩌면 둘 다인지도 모르겠다. 

덧붙이자면 설치 방법은 위와 같이 세 가지인데 내 경우는 현재 (왜 그랬는지 기억은 안 나지만) native로 설치돼 있다. 추가로 '~/.claude.json' 파일의 autoUpdates 필드 값이 false로 돼 있어서 true로 변경하고 파일을 저장했다. 'claude doctor' 명령으로 자동 업데이트가 활성화된 것을 확인했다.

끝.