Claude Code 자주 막히는 에러 10가지 한국어 해결법

Claude Code를 처음 설치하면 의외로 자잘한 에러가 많이 뜹니다. 검색해도 영어 문서뿐이라 막막한 분들을 위해, 제가 직접 막혔던 순서대로 정리했습니다.

이 글은 코드를 한 번도 짜본 적 없는 분도 따라올 수 있게 썼습니다. 터미널(검은 화면에 명령어를 입력하는 프로그램)이 낯설어도 괜찮습니다. 각 에러마다 "왜 이런 메시지가 뜨는지"부터 차근차근 풀이합니다.

참고로 글 작성 시점 기준 Claude Code는 Anthropic이 공식 배포 중인 CLI(명령줄) 도구이며, Node.js 18 이상 환경에서 돌아갑니다.

Claude Code 에러, 왜 이렇게 자주 나는가

Claude Code 에러의 대부분은 "프로그램 자체 버그"가 아니라 설치 환경·권한·API 키 설정 세 가지에서 생깁니다. 도구를 의심하기 전에 내 컴퓨터 환경부터 점검하면 거의 풀린다는 뜻입니다.

비유하자면 새로 산 가전제품을 콘센트에 안 꽂고 "왜 안 켜지지" 하는 상황과 비슷합니다. Claude Code는 똑똑하지만, 동작에 필요한 전제 조건이 꽤 까다롭습니다.

제가 맥과 윈도우(WSL) 양쪽에서 직접 설치하며 겪은 빈도순으로 10가지를 추렸습니다.

빈도	에러 유형	발생 시점
매우 잦음	command not found	설치 직후
매우 잦음	API 키 인증 실패	첫 실행
잦음	권한 거부(EACCES)	npm 설치 중
잦음	Node 버전 미달	설치 시도
보통	한글 깨짐	출력 확인 시
보통	프록시·네트워크 차단	사내망 사용 시
보통	토큰 한도 초과	사용 중
가끔	파일 경로 인식 실패	코드 작업 중
가끔	Git 관련 충돌	변경 적용 시
가끔	업데이트 실패	버전 갱신 시

1. command not found: claude

설치는 끝났는데 claude 라고 치면 "command not found"가 뜬다면, 이건 컴퓨터가 claude라는 명령을 어디서 찾아야 할지 모르는 상태입니다.

zsh: command not found: claude

원인은 보통 두 가지입니다. (1) 설치는 됐는데 터미널이 새 명령을 아직 인식 못 함, (2) PATH(컴퓨터가 명령어를 찾는 폴더 목록)에 설치 경로가 빠짐.

가장 먼저 시도할 해결책은 터미널을 완전히 껐다가 새로 여는 것입니다. 저도 처음 설치했을 때 이 한 줄로 풀렸습니다. 안 되면 아래 명령으로 설치 위치를 확인합니다.

npm list -g --depth=0

목록에 @anthropic-ai/claude-code가 보이면 설치는 정상이고, PATH만 문제입니다. 맥이라면 ~/.zshrc 파일에 export PATH=$PATH:$(npm config get prefix)/bin 한 줄을 추가하고 터미널을 재시작하면 됩니다.

2. API 키 인증 실패 (Invalid API key)

첫 실행 후 Invalid API key 또는 authentication_error가 뜨면, Anthropic 콘솔에서 발급받은 키가 제대로 입력되지 않았다는 뜻입니다. API 키는 일종의 출입증입니다.

제가 가장 흔하게 보는 실수는 키를 복사할 때 앞뒤 공백이 따라오거나, 키 일부가 잘리는 경우입니다. 키는 sk-ant-로 시작하는 긴 문자열이라 한 번에 다 선택됐는지 꼭 확인해야 합니다.

💡 API 키는 한 번 발급받으면 화면에 다시 표시되지 않습니다. 발급 직후 메모장에 따로 보관하세요.

해결 절차는 이렇습니다.

1. console.anthropic.com에 로그인 → API Keys 메뉴
2. 새 키 발급 (Create Key)
3. 터미널에서 claude 실행 후 안내에 따라 키 붙여넣기
4. 그래도 안 되면 ~/.claude/ 폴더의 설정 파일을 지우고 다시 시도

참고로 무료 크레딧이 소진된 계정도 같은 에러처럼 보입니다. 콘솔의 Billing 메뉴에서 잔액을 함께 확인하세요.

3. Node 버전이 낮다고 나올 때

Claude Code requires Node.js 18 or higher 메시지는 그대로 받아들이면 됩니다. Node.js가 너무 오래된 버전이라는 뜻입니다.

Node.js는 자바스크립트라는 언어로 만들어진 프로그램을 실행시켜주는 엔진입니다. Claude Code도 이 위에서 돌아갑니다.

확인은 간단합니다.

node -v

v16.x.x 같은 결과가 나오면 업데이트가 필요합니다. 맥은 brew install node@20, 윈도우는 nodejs.org에서 LTS 버전을 새로 받아 설치하면 됩니다. 저는 처음에 v14가 깔려 있는 줄도 몰랐는데, 이걸 v20으로 올리는 데만 20분 걸렸습니다.

4. EACCES 권한 거부

EACCES: permission denied 에러는 이 폴더에 파일을 쓸 권한이 없다는 뜻입니다. npm으로 전역 설치할 때 가장 흔히 나옵니다.

급한 마음에 sudo npm install -g ...로 강제 설치하는 분이 많은데, 이건 권장하지 않습니다. 나중에 더 큰 권한 꼬임을 만들 수 있거든요.

대신 npm의 전역 설치 경로를 내 홈 폴더로 바꾸는 게 정석입니다.

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

그리고 PATH에 ~/.npm-global/bin을 추가한 뒤 다시 설치하면 깔끔하게 됩니다. 처음엔 헷갈렸지만 한 번만 해두면 평생 안 마주칠 에러입니다.

5. 한글 출력이 깨질 때

윈도우 터미널에서 Claude Code 응답에 한글이 ???나 이상한 기호로 나온다면, 터미널 인코딩이 UTF-8이 아니라서 그렇습니다.

해결법은 두 단계입니다.

chcp 65001

이 명령은 현재 터미널을 UTF-8 모드로 바꿉니다. 다만 터미널을 닫으면 초기화되므로, Windows Terminal의 설정에서 기본 인코딩을 UTF-8로 지정하거나 WSL(윈도우에서 리눅스를 쓰게 해주는 기능)을 쓰는 게 더 안정적입니다.

맥에서는 거의 발생하지 않습니다. 발생한다면 ~/.zshrc에 export LANG=ko_KR.UTF-8 한 줄 추가하세요.

6. 프록시·방화벽으로 막힐 때

회사망이나 학교 와이파이에서 ENOTFOUND 또는 ETIMEDOUT이 뜬다면, 외부 API 호출이 차단된 환경일 가능성이 높습니다.

Error: connect ETIMEDOUT api.anthropic.com

확인 절차는 다음과 같습니다.

• [ ] 모바일 핫스팟에 연결해서 같은 명령을 다시 시도해본다
• [ ] 잘 되면 → 네트워크 문제 확정
• [ ] 회사 IT 담당자에게 api.anthropic.com 도메인 허용 요청
• [ ] 프록시가 필요하면 HTTPS_PROXY 환경 변수 설정

솔직히 사내망 정책은 회사마다 달라서 일반적인 해결책이 없습니다. 저도 한 번은 카페에서 쓰면 잘 되고 사무실에선 안 돼서 한참 헤맸습니다.

7. 토큰 한도 초과 (rate limit)

rate_limit_error나 usage limit reached는 짧은 시간에 너무 많은 요청을 보냈거나, 월 사용량 한도에 도달했다는 신호입니다.

Error: 429 - rate_limit_exceeded

원인별 대응이 다릅니다.

원인	증상	해결
분당 요청 초과	잠깐 뒤 풀림	1~2분 기다린 후 재시도
일일 토큰 초과	다음날까지 막힘	콘솔에서 한도 상향 신청
크레딧 소진	결제 안 됐다는 메시지	Billing에서 결제 수단 등록

Claude Code는 한 번의 작업에서도 파일을 여러 개 읽으면 토큰을 빠르게 씁니다. 큰 프로젝트 폴더를 통째로 분석시키면 한 번에 수십만 토큰이 소모되기도 합니다.

8. 파일 경로를 못 찾는다고 할 때

File not found 또는 ENOENT는 지정한 파일이 그 위치에 없다는 뜻입니다. 비개발자가 가장 자주 겪는 이유는 단순합니다 — 현재 터미널이 보고 있는 폴더가 내가 생각하는 폴더와 다름.

pwd

이 명령은 "지금 내가 어느 폴더에 있는지"를 보여줍니다. 결과가 예상과 다르면 cd 경로로 원하는 폴더로 이동한 뒤 다시 시도하세요.

또 하나, 윈도우 경로는 역슬래시(\)인데 Claude Code는 슬래시(/)를 선호합니다. C:/Users/myname/project 식으로 적는 게 안전합니다.

9. Git 충돌이 났을 때

Claude Code가 코드를 수정하다가 merge conflict나 unstaged changes 같은 메시지를 띄울 수 있습니다. Git(코드 변경 이력을 기록하는 도구)이 "이 파일은 이미 다른 변경이 있어서 덮어쓸 수 없다"고 막는 상황입니다.

가장 안전한 방법은 Claude Code에게 작업을 시키기 전에 현재 상태를 먼저 저장하는 겁니다.

git status
git add .
git commit -m "before claude work"

이렇게 한 번 묶어두면 Claude Code가 뭔가 잘못 만져도 언제든 되돌릴 수 있습니다. 솔직히 저도 이 습관을 들이기 전엔 작업물 날린 적이 두 번 있습니다.

10. 업데이트 실패 (npm update 에러)

claude --version 결과가 최신이 아니거나 업데이트가 실패하면, 보통 권한 문제이거나 캐시가 꼬인 경우입니다.

npm cache clean --force
npm uninstall -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code

이 세 줄을 순서대로 실행하면 캐시를 비우고 깨끗이 재설치합니다. 그래도 안 되면 4번 항목의 권한 설정부터 다시 점검하세요. 대부분 거기서 막힙니다.

에러를 줄이는 평소 습관

같은 에러를 두 번 겪지 않으려면 환경을 단정하게 유지하는 게 제일입니다. 제가 시행착오 끝에 정착한 체크리스트입니다.

• [ ] Node.js는 LTS(짝수) 버전만 사용 (홀수 버전은 실험적)
• [ ] 전역 npm 설치 경로를 홈 폴더로 지정해두기 (4번 참고)
• [ ] API 키는 비밀번호 관리 앱에 백업
• [ ] 큰 작업 전엔 항상 git commit 한 번
• [ ] 월 1회 npm update -g로 도구 최신화

        에러 발생
            ↓
    [환경 점검 3단계]
    Node 버전 → PATH → 권한
            ↓
       대부분 해결
            ↓
    그래도 안 되면
       → API/네트워크

처음엔 이 흐름이 낯설지만, 두세 번 반복하면 에러 메시지만 봐도 어디부터 봐야 할지 감이 잡힙니다.

솔직한 아쉬움

Claude Code는 강력하지만, 비개발자 입장에서 진입 장벽은 여전히 높은 편입니다. 공식 문서가 영어 위주라 검색이 어렵고, 에러 메시지도 친절하지 않습니다.

특히 윈도우 사용자는 WSL 설치까지 거쳐야 안정적으로 쓸 수 있어서 초기 세팅에만 1~2시간이 걸립니다. 챗봇 GUI에 익숙한 분이라면 이 부분에서 좌절하기 쉽습니다.

그래도 한 번 환경을 잡아두면, 블로그 글 자동화·엑셀 데이터 정리·간단한 웹페이지 만들기 같은 작업이 채팅창에서 그냥 말로 됩니다. 이 효율은 다른 도구로 대체하기 어렵습니다.

마무리

여기 정리한 10가지는 글 작성 시점 기준 제가 직접 겪고 풀었던 에러입니다. 같은 메시지가 떴다면 해당 항목부터 보시면 시간이 많이 절약될 겁니다.

가장 중요한 건 에러 메시지를 무서워하지 않는 태도입니다. 빨간 글씨가 떠도 그건 그저 컴퓨터가 "이게 빠졌어요" 하고 알려주는 것뿐입니다. 다음에 새 에러를 만나면 메시지 전체를 그대로 복사해서 Claude에게 물어보세요. 의외로 답을 잘 줍니다.

다음 글에서는 Claude Code로 실제 비개발자가 할 수 있는 자동화 예시 5가지를 다뤄볼 예정입니다.

함께 보면 좋은 글

• Claude Artifacts 사용법 10가지, 코딩 몰라도 앱처럼 쓰기
• Claude Code Skills 활용법, 직접 만든 5가지 스킬 후기
• Claude Artifacts 예시 7가지 — 직접 만들어본 미니앱