Claude Code exit code 3 오류, Node 업그레이드로 해결

Claude Code 오류 해결

Claude Code를 실행했는데 아무 반응 없이 exit code 3만 뜨고 꺼지는 경우가 있어요. 이 오류는 Claude Code가 요구하는 최소 Node.js 버전을 충족하지 못할 때 발생해요. 정상적인 실행이라면 Claude Code 인터페이스가 바로 뜨는데, 이 오류가 나면 터미널에 숫자 하나만 찍히고 아무 일도 일어나지 않아요. 처음 보면 뭐가 잘못된 건지 감이 안 잡혀서 당황스러울 수 있어요.

📌 3줄 요약

· exit code 3은 Node.js 에러가 아니라 Claude Code가 자체 정의한 종료 코드예요.

· 원인은 대부분 Node.js 18 버전 사용이고, 20 이상(권장 22 LTS)으로 올리면 해결돼요.

· 업그레이드 후에는 터미널을 완전히 닫았다가 다시 열어야 새 버전이 인식돼요.

목차

1. exit code 3이 뜨는 원인 파악

2. 현재 Node.js 버전 확인하기

3. Node.js 최신 LTS 버전으로 업그레이드

4. 업그레이드 후 Claude Code 실행 확인

exit code 3이 뜨는 원인 파악

🔍 exit code 3이란?

exit code 3은 Node.js 자체에서 내보내는 코드가 아니에요. Claude Code 내부에서 실행 환경을 점검한 뒤, 조건이 맞지 않으면 프로세스를 종료 코드 3으로 끝내는 구조예요. 일반적인 Node.js 에러 코드는 1이나 2인데, 3은 Claude Code가 자체적으로 정의한 종료 코드라서 구글에 검색해도 정보가 별로 없어요. 그래서 원인을 파악하는 데 시간이 오래 걸리는 편이에요.

특히 Node.js 18 버전대를 사용하는 경우 이 문제가 자주 나타나요. Claude Code는 2025년 하반기 업데이트부터 Node.js 18 지원을 공식 종료했기 때문이에요. Node.js 18은 2025년 4월에 EOL(End of Life)을 맞았고, 보안 패치도 더 이상 제공되지 않아요. Claude Code 팀도 이 시점에 맞춰서 최소 요구 버전을 올린 거예요. 학교 컴퓨터나 오래전에 세팅해 둔 개인 PC에서 이 문제가 특히 많이 발생해요.

에러 메시지가 친절하지 않아서 원인을 찾기 어려운 편이에요. 터미널에 "exit code 3"만 한 줄 찍히고, 어디서 무엇이 잘못됐는지 알려주지 않아요. "Node.js 버전이 낮습니다"같은 안내 문구가 있으면 바로 알 수 있을 텐데, 그런 메시지가 전혀 없어요. 그래서 처음에는 API 키 문제인 줄 알고 키를 재발급받거나, Claude Code를 재설치하는 등 엉뚱한 삽질을 하게 돼요.

💬 제 경험

제가 직접 겪었을 때도 한참 헤맸어요. 처음에는 API 키 문제인 줄 알고 키를 재발급받기까지 했는데, 결국 Node.js 버전이 원인이었어요. GitHub Issues에서 같은 증상을 검색해서야 비로소 원인을 알게 됐어요. 이 글을 읽고 계신 분들은 저처럼 시간 낭비하지 않으셨으면 좋겠어요.

현재 Node.js 버전 확인하기

해결에 앞서 지금 설치된 Node.js 버전부터 확인해야 해요. 터미널을 열고 아래 명령어를 입력해요. Windows라면 명령 프롬프트(cmd)나 PowerShell 어느 쪽이든 상관없어요. macOS나 Linux라면 기본 터미널을 그대로 사용하면 돼요.

 

node -v를 입력하면 v18.20.4처럼 현재 버전이 출력돼요. 앞자리가 18이라면 이것이 exit code 3의 원인이에요. 버전 번호에서 가장 앞의 숫자(메이저 버전)만 확인하면 돼요. 뒤쪽 숫자(마이너, 패치)는 이 문제와 관련이 없어요.

Claude Code 공식 문서에서는 Node.js 20 이상을 요구해요. 정확히는 Node.js 20.17.0 이상, 또는 22.x LTS 버전을 권장하고 있어요. 2026년 8월 현재 기준으로는 Node.js 22가 활성 LTS 버전이라서 22를 설치하는 것을 추천해요. Node.js 20도 여전히 지원 기간 안이라 사용해도 문제없어요.

⚠️ node 명령어가 아예 인식되지 않는다면

만약 node 명령어 자체가 인식되지 않는다면 Node.js가 아예 설치되지 않은 상태예요. 이 경우에도 동일하게 exit code 3이 발생할 수 있으니, 바로 설치를 진행하면 돼요. "node는 내부 또는 외부 명령이 아닙니다"라는 메시지가 뜨면 설치가 안 된 거예요. 환경 변수 PATH에 Node.js 경로가 빠져 있을 수도 있으니, 설치했는데 인식이 안 되면 PATH도 확인해 보세요.

💡 npm 버전도 같이 확인해 두세요

추가로 npm -v도 같이 확인해 두면 좋아요. Node.js를 업그레이드하면 npm도 함께 올라가기 때문에, 이전 버전을 기록해 두면 나중에 비교가 편해요. npm 버전은 Claude Code 설치(npm install -g)에 직접 영향을 주기 때문에 함께 챙기는 게 좋아요.

 

Node.js 최신 LTS 버전으로 업그레이드

1 Windows 환경 기준으로 가장 간단한 방법은 공식 사이트에서 설치 파일을 다시 받는 거예요. nodejs.org에 접속하면 LTS(장기 지원) 버전 다운로드 버튼이 바로 보여요. 사이트에 들어가면 두 개의 다운로드 버튼이 나오는데, 왼쪽이 LTS이고 오른쪽이 Current예요. 반드시 왼쪽 LTS 버튼을 클릭해야 해요.

2 설치 파일을 실행하면 기존 Node.js 18을 자동으로 덮어써요. 별도로 이전 버전을 삭제할 필요 없이, 설치 마법사의 Next 버튼만 누르면 돼요. 설치 경로를 기본값(C:\Program Files\nodejs\)으로 두면 기존 설치를 깔끔하게 교체해 줘요. 중간에 "Tools for Native Modules" 체크박스가 나오는데, 체크하지 않아도 Claude Code 사용에는 문제없어요.

3 설치가 완료되면 터미널을 완전히 닫았다가 새로 열어야 해요. 기존 터미널 세션에는 이전 경로가 캐시(cache)되어 있어서, 새 버전이 인식되지 않을 수 있어요. VS Code 내장 터미널을 사용하는 경우에는 VS Code 자체를 재시작하는 것이 가장 확실해요. 터미널 탭만 닫고 새로 여는 것으로는 반영이 안 될 때가 있어요.

LTS 버전을 선택하는 것이 중요해요.

구분	특징	권장
LTS (장기 지원)	안정성 면에서 LTS가 더 나아요. Claude Code를 포함한 대부분의 개발 도구들은 LTS 버전을 기준으로 테스트해요.	O
Current (최신)	Current 버전은 최신 기능이 들어가 있지만, 예상치 못한 호환성 문제가 생길 수 있으니 피하는 게 좋아요.	X

nvm(Node Version Manager)을 사용하는 경우라면 터미널에서 바로 처리할 수 있어요. nvm install 22를 입력한 뒤, nvm use 22로 전환하면 끝이에요.

🔍 nvm이 뭔가요?

nvm은 여러 버전의 Node.js를 동시에 설치해 두고 자유롭게 전환할 수 있는 도구예요. 아직 nvm을 쓰지 않더라도 이번 기회에 설치해 두면 나중에 버전 관리가 훨씬 편해져요.

 

💬 제 경험

제가 직접 해본 결과, nvm 방식이 훨씬 편해요. 나중에 다른 프로젝트에서 Node 18이 필요해지면 nvm use 18로 바로 돌아갈 수 있기 때문이에요. 설치 파일을 따로 보관할 필요도 없고, 명령어 한 줄로 원하는 버전을 받을 수 있어요. 특히 여러 프로젝트를 동시에 관리하는 분들에게는 nvm이 거의 필수 도구예요.

업그레이드 후 Claude Code 실행 확인

Node.js 업그레이드가 끝나면 버전부터 다시 확인해요. node -v를 입력해서 v20.x 또는 v22.x가 표시되는지 봐요. 여기서 메이저 버전이 20 이상으로 나오면 준비가 된 거예요. 혹시 여전히 18로 나온다면 터미널을 다시 열었는지 확인해 보세요.

 

버전이 올라간 것을 확인했으면 claude를 입력하여 Claude Code를 실행해요. exit code 3 없이 정상적으로 인터페이스가 뜨면 문제가 해결된 거예요. 처음 실행 시 Claude Code가 업데이트를 체크하는 과정이 있어서 몇 초 걸릴 수 있어요. "Welcome to Claude Code"라는 문구가 보이면 성공이에요.

혹시 여전히 실행되지 않는다면 Claude Code 자체를 재설치해 봐요. npm install -g @anthropic-ai/claude-code 명령어로 최신 버전을 다시 받을 수 있어요. -g 플래그는 전역 설치를 의미하는데, Claude Code는 반드시 전역으로 설치해야 해요. 이 명령어를 실행하면 기존 Claude Code를 최신 버전으로 덮어쓰기해요.

 

⚠️ 재설치해도 안 될 때는 npm 캐시를 의심하세요

재설치 후에도 문제가 지속된다면 npm 캐시 문제일 가능성이 있어요. npm cache clean --force를 실행한 뒤 다시 설치를 시도해요. npm 캐시에 이전 버전의 파일이 남아서 충돌을 일으키는 경우가 간혹 있어요. 캐시를 지운 뒤 재설치하면 깨끗한 상태에서 새로 받아오기 때문에 대부분 해결돼요.

💬 제 경험

대부분의 경우 Node.js 버전만 올리면 바로 해결돼요. 제가 주변 사람들 환경도 여럿 세팅해 봤는데, exit code 3은 열에 아홉이 Node 버전 문제였어요. 나머지 한 건은 Node.js 설치 자체가 깨져 있어서 완전히 삭제 후 재설치로 해결했어요. 이 글에 나온 순서대로만 따라 하면 대부분 5분 안에 해결할 수 있을 거예요.

💡 LTS는 짝수 번호라는 규칙

한 가지 팁을 드리자면, Node.js LTS 버전은 짝수 번호(20, 22, 24)라는 규칙이 있어요. 짝수 버전을 설치하면 장기 지원을 받을 수 있으니 기억해 두면 유용해요. 홀수 버전(19, 21, 23)은 6개월만 지원하고 끝나기 때문에, 꼭 짝수 버전을 선택하세요. 앞으로 Node.js를 업데이트할 일이 생기면 짝수만 기억하면 돼요.

✍️ 마치며

exit code 3은 메시지가 워낙 불친절해서 처음 만나면 API 키나 설치 자체를 의심하기 쉬운 오류예요. 하지만 정체를 알고 나면 Node.js 버전 하나만 올리면 끝나는 문제랍니다.

터미널에 node -v 한 줄만 쳐보는 것부터 시작해 보세요. 앞자리가 18이라면 오늘 바로 22 LTS로 올리시고, 설치가 끝나면 터미널을 완전히 닫았다가 새로 여는 것도 잊지 마세요.

#ClaudeCode #exitcode3 #Node.js #Nodejs업그레이드 #LTS #nvm #개발환경세팅 #클로드코드오류 #npm #터미널