Claude Code 오류: 자주 발생하는 5가지 문제와 빠른 해결 방법 (2026)

Claude Code는 업데이트가 빨라서 명령어 이름과 동작이 바뀔 수 있어요. 직접 확인해야 할 부분은 그때그때 짚어 드릴게요. 확실한 정보가 필요할 때는 Claude Code 공식 문서를 함께 참고하세요.

오류 빠른 조회 (증상 → 해결)

여기가 핵심 참고 섹션이에요. 지금 보이는 메시지에 맞는 행을 찾아 마지막 열을 따르고, 원인을 이해하고 싶다면 상세 섹션으로 넘어가세요.

고치기 전에: 내 문제일까, Anthropic 문제일까?

초보자가 가장 흔히 하는 실수는, 사실 서버 쪽 문제인데도 곧바로 재설치와 설정 수정에 뛰어드는 거예요. 각 해결에 들어가기 전에 30초만 들여 이렇게 구분해 보세요:

• 내 쪽 (환경/설정): command not found, 잘못된 PATH, 깨진 인증, 권한 차단, 가득 찬 컨텍스트. 알아보는 법: 실행할 때마다 같은 메시지가 일관되게 반복돼요.
• Anthropic 쪽 (내가 고칠 수 없음): overloaded 메시지, 네트워크는 멀쩡한데 모델이 응답하지 않음, 아무것도 안 바꿨는데 갑자기 나타나는 오류. 알아보는 법: 갑작스럽고 보통 몇 분 안에 저절로 풀려요.

빠르게 분류하는 세 가지 명령: claude --version(제대로 설치됐나요?) → /status(지금 어느 경로인가, 할당량은 남았나?) → Anthropic 공식 상태 페이지 열기 (시스템 장애는 없나?). 세 가지 모두 괜찮은데도 여전히 막힌다면, 그때가 로컬 환경을 고칠 때예요.

오류 1 - 설치했는데 claude 가 실행되지 않음 (command not found / PATH)

증상. 설치는 끝났는데 claude 를 입력하면 다음 메시지 중 하나가 떠요:

# macOS / Linux (zsh, bash)
zsh: command not found: claude

# Windows (PowerShell / CMD)
claude : The term 'claude' is not recognized as the name of a cmdlet...

답답한 점은, npm 는 설치 성공이라고 하는데 터미널은 여전히 명령어를 찾지 못한다는 거예요.

원인. 패키지는 npm의 global bin 폴더에 놓였지만, 그 폴더가 PATH 환경 변수에 없어서 셸이 claude 바이너리의 위치를 알지 못해요. Windows에서는 한 창에서 설정한 환경 변수가 새 창을 열면 사라져 있는 경우가 많아요.

해결. 먼저 npm의 global bin 폴더를 찾으세요:

npm config get prefix
# e.g. returns: /Users/you/.npm-global (macOS)
# or: C:\Users\you\AppData\Roaming\npm (Windows)

명령어는 PREFIX/bin (macOS/Linux) 또는 PREFIX 자체 (Windows)에 있어요. 이것을 PATH에 추가하세요:

# macOS / Linux - append to the end of ~/.zshrc (or ~/.bashrc)
export PATH="$(npm config get prefix)/bin:$PATH"
# then reload
source ~/.zshrc

# verify
claude --version

Windows에서는 PowerShell 프로필을 열어 같은 줄을 추가하거나, npm 경로를 시스템 PATH 변수(설정 → 환경 변수)에 추가한 뒤 터미널을 다시 여세요. 하지만 제 실용적인 추천은 이거예요: Windows에서는 Claude Code를 WSL2 안에서 실행하세요 네이티브 PowerShell/CMD 대신에요. Linux 환경이 Windows 특유의 성가신 PATH·권한 문제를 거의 다 피하게 해 줘요.

PATH를 고쳤는데도 인식되지 않는다면, 애초에 처음 설치가 깔끔하지 않았을 가능성이 커요. Claude Code를 제대로 설치하는 방법 을 다시 보고 처음부터 깔끔하게 다시 하세요.

오류 2 - 로그인 불가 / 인증 실패 (API 키 vs 구독)

증상. 브라우저에서 로그인이 멈추거나, unauthorized 라고 뜨거나, Pro/Max 플랜으로 이미 로그인했다고 생각하는데도 Claude Code가 계속 API 키를 요구해요.

원인. 여기서 문제를 일으키는 원인은 주로 두 가지예요. 하나는 손상된 자격 증명 캐시 - 오래된 토큰이 남아 있는 경우죠. 둘째, 그리고 더 흔한 건 두 인증 경로의 혼동 이에요: 구독(계정을 통한 Pro/Max 플랜)으로 로그인하는 것과 ANTHROPIC_API_KEY(토큰당 과금)을 쓰는 건 완전히 달라요. 만약 ANTHROPIC_API_KEY 환경 변수를 설정한 적이 있다면, Claude Code가 API 키 경로를 우선해 돈 내는 플랜을 무시할 수 있어요.

해결. 먼저 자격 증명을 초기화하세요:

claude logout
claude login # sign in again on the route you want (subscription)

그다음, API 키 변수가 '새치기'하고 있지 않은지 확인하세요:

# macOS / Linux
echo $ANTHROPIC_API_KEY

# Windows (PowerShell)
echo $env:ANTHROPIC_API_KEY

Pro/Max 플랜을 쓰고 싶은데 이 변수에 값이 있다면, 셸 프로필(export ANTHROPIC_API_KEY=... 줄, .zshrc 등, Windows라면 환경 변수)에서 지우고 터미널을 다시 여세요. 마지막으로 /status 를 Claude Code 안에서 실행해 올바른 경로인지 확인하세요. 반대로 일부러 API 키를 쓰려는 거라면, 그 키가 여전히 유효하고 크레딧이 있는지 확인하세요.

오류 3 - 'Rate limit reached' / 429 오류

증상. 잘 진행하다가 Rate limit reached 메시지나 429 코드가 뜨며 작업 중간에 멈춰요. 거의 쓰지 않았는데도 뜨기도 하고요.

원인. 함정은 서로 다른 두 시스템이 같은 문구를 낸다 는 점이에요. 게다가 대처법은 정반대죠:

해결. 먼저 /status 로 경로를 파악하세요. 그다음 남은 프로세스를 찾으세요 - Claude Code는 창을 닫은 뒤에도 백그라운드에 프로세스를 남기기도 하고, 그게 계속 할당량을 갉아먹어요:

# macOS / Linux - list live claude processes
ps aux | grep claude
# see a stray PID? kill it: kill <PID>

# Windows: open Task Manager, find lingering node/claude processes and end them

경로가 구독 플랜이고 정말로 다 썼다면, 기간 리셋을 기다리거나 사용량을 아끼려고 잠시 더 가벼운 모델로 바꾸는 것 말고는 요령이 없어요. API 키라면 한도 상향은 계정 등급 문제고요. 특정 429가 어떤 규칙에서 왔는지 정확히 알고 싶다면, anthropics/claude-code 저장소의 이슈를 참고하세요.

오류 4 - Claude Code가 작업 중 멈춤/정지 (컨텍스트 가득참)

증상. 세션이 얼어붙고, 응답이 기어가듯 느려지고, 모델이 처음에 한 말을 '잊기' 시작하거나, 끝나지 않는 편집·재편집 루프에 빠져요.

원인. 보통은 가득 찬 컨텍스트 창 이에요: 대화가 아주 길어졌거나, 거대한 파일을 붙여 넣었거나, 출력이 부풀 만큼 큰 작업 하나를 통째로 맡긴 경우죠. 이건 서버 오류가 아니에요 - 그러니 Anthropic 쪽의 overloaded 메시지와 혼동하지 마세요.

해결. 가벼운 것부터 무거운 것 순으로:

• /compact - 대화를 압축해 핵심은 남기면서 여유를 만들어요. 지금 하던 작업을 계속 이어 가고 싶을 때 쓰세요.
• /clear - 컨텍스트를 지우고 새로 시작해요. 관련 없는 작업으로 넘어갈 때 쓰세요.
• 작업을 순차적인 조각으로 나누기. '모듈 전체를 리팩터링' 대신 한 번에 한 파일씩 맡기세요. 여기서는 예방이 치료보다 나아요.
• 거대한 파일을 통째로 채팅에 붙여 넣지 마세요 - 전부 컨텍스트에 밀어 넣는 대신, 필요할 때 Claude Code가 직접 파일을 읽게 하세요.
• 완전히 얼어붙었다면: 세션을 종료(Ctrl+C)하고 다시 여세요. 지금 컨텍스트는 잃지만, 멈춘 상태는 확실히 끝나요.

멈춤을 피하기 위한 컨텍스트 관리를 더 깊이 파고들고 싶다면, Claude Code 시작을 위한 10단계 의 체계적이고 초보자 친화적인 워크플로가 처음부터 작업을 깔끔하게 넘기는 데 도움이 돼요.

오류 5 - 권한에 막힘 (명령을 실행할 수 없음)

증상. Claude Code가 명령마다 확인을 요구하거나, 명령 실행·파일 편집을 아예 거부해 작업 흐름을 끊어요.

원인. 이건 대개 '버그'가 아니라 안전 기능 이에요: 권한 모드가 접근을 허용할 때까지 위험한 작업을 막고 있는 거죠. 기본적으로 Claude Code는 파일을 수정/삭제하거나 셸을 실행할 수 있는 명령에 신중해요.

해결. 통제된 방식으로 접근을 허용하세요:

• Claude Code가 물어보면, 매번 승인을 누르는 대신 신뢰하는 작업에는 세션 단위 접근을 선택하세요.
• 자주 쓰는 명령을 허용 목록 에 추가하면 더 이상 묻지 않아요.
• 여러 권한 모드를 이해해서, 지금 하는 일에 맞는 수준을 고를 수 있게 하세요.

솔직한 경고: 단지 '더 빠르게' 하려고 모든 확인을 건너뛰는 모드를 켜지 마세요. 그러면 Claude Code가 묻지 않고 어떤 명령이든 실행해요 - 편하지만, 중요한 컴퓨터나 저장소에서 모델이 예상치 못한 일을 하면 진짜 위험이 돼요. 격리된 환경(샌드박스/컨테이너)에서만 쓰세요.

안전한 권한 설정에는 여러 층이 있어서, 전용 심층 안내로 따로 정리했어요 → Claude Code 권한과 권한 모드. 한 번 설정하면 오래 믿고 쓸 수 있어요.

여전히 작은 오류가 나나요? 체크리스트와 재설치 시점

위 5개 그룹을 다 거쳤는데도 이상한 작은 오류가 계속 잡힌다면, 재설치를 떠올리기 전에 이 체크리스트를 처음부터 끝까지 실행해 보세요:

• 최신 빌드로 업데이트: npm i -g @anthropic-ai/claude-code - 많은 버그가 이후 릴리스에서 고쳐져요.
• Node가 LTS 버전인지 확인하세요 (어이없는 오류 중에는 Node가 너무 오래됐거나 너무 새것이어서 생기는 것도 있어요).
• 프로젝트당 터미널 하나 로 Claude Code를 실행해 충돌과 남는 프로세스를 피하세요.
• 자격 증명 캐시를 claude logout 로 지우고 다시 로그인하세요.
• 깔끔한 재설치: 완전히 제거한 뒤 Claude Code 설치 가이드 를 따라 다시 설치하세요.
• 이 도구가 실제로 어떻게 동작하는지 잘 모르겠다면? Claude Code란 무엇인가 를 다시 읽고 올바른 멘탈 모델을 세우세요 - 많은 '오류'는 사실 동작 방식에 대한 오해예요.

Anthropic 지원에 연락할 때: 깨끗한 컴퓨터에서도 사라지지 않는 오류, overloaded 메시지가 몇 시간씩 반복되는 경우, 또는 스스로 조정할 수 없는 결제·계정 문제.

미리 만든 키트(AgentKit)로 오류는 줄이고 힘은 키우기

작은 오류의 상당수는 컴퓨터마다 환경이 달라서 생겨요: 뒤틀린 PATH, 흩어진 설정, 표준 스킬이나 스테이터스라인 부재 같은 거죠. 수동 설정과 씨름하는 걸 그만두고 싶다면, Claude Code용 AgentKit 키트 에는 작업 환경을 표준화해 주는 바로 쓸 수 있는 설정, 스킬, 심지어 스테이터스라인 빌더까지 들어 있어요. 성가신 설정 오류를 상당수 미리 막고 세션을 더 안정적으로 유지해 주죠. 위 CLI 오류를 대신 '고쳐' 주진 않지만, 애초에 생길 가능성을 줄여 줘요. 써 보고 싶다면 AgentKit 사용해 보기 (링크로 20% 할인) 로 이 미리 만든 세팅이 여러분의 방식에 맞는지 확인해 보세요.

자주 묻는 질문 (FAQ)

왜 claude 를 입력하면 command not found가 뜨나요?

명령어가 든 폴더(npm의 global bin)가 PATH 환경 변수에 없어서 셸이 바이너리를 못 찾기 때문이에요. npm config get prefix 를 실행하고, 맞는 /bin 폴더를 PATH에 추가한 뒤 터미널을 다시 여세요.

Claude Code가 Windows / PowerShell에서 실행되나요?

실행돼요. 다만 네이티브 PowerShell/CMD보다 WSL2에서 경험이 훨씬 매끄러워요. WSL2는 Windows 특유의 PATH·권한 문제 대부분을 피해 줘요.

'Rate limit reached'는 얼마나 지속되나요?

원인에 따라 달라요. Pro/Max 플랜 할당량이라면 기간이 리셋될 때까지 기다려야 해요. API 키의 RPM/TPM 제한이라면 동시 요청을 줄이면 즉시 풀려요. /status 를 실행해 어느 쪽에 걸렸는지 확인하세요.

Claude Code가 멈추면 어떻게 하나요?

보통은 컨텍스트가 가득 찬 거예요. /compact 로 대화를 압축하거나 /clear 로 초기화하고, 작업을 더 작게 나누고, 거대한 파일 붙여넣기를 피하세요. 완전히 얼어붙었다면 세션을 종료(Ctrl+C)하고 다시 여세요.

로그인 오류는 API 키 때문인가요, 플랜 때문인가요?

먼저 ANTHROPIC_API_KEY 변수를 확인하세요: 값이 있으면 Claude Code가 결제한 플랜 대신 API 키 경로를 탈 수 있어요. Pro/Max 플랜을 쓰려면 그 변수를 지운 뒤 claude logout 와 claude login 를 다시 실행하세요.

Claude Code를 어떻게 재설치하나요?

기존 패키지를 제거하고 npm i -g @anthropic-ai/claude-code 를 다시 실행하고, Node가 LTS 버전인지 확인하고, npm의 global bin 폴더가 PATH에 있는지 확인하세요. 그런 다음 claude login 를 처음부터 실행하세요.

결론 + 다음 단계

핵심: 아무렇게나 고치지 마세요. 먼저 구분하세요 - 내 문제인가, Anthropic 문제인가 - 그다음 해당 증상 그룹에 맞춰 고치세요: 실행 안 됨/PATH, 인증, 속도 제한, 멈춤/컨텍스트, 권한. 세 명령 claude --version, /status, 그리고 /compact 면 하루하루의 대부분 상황을 처리할 수 있어요. 설치하자마자 오류가 난다면 Claude Code 설치 가이드 로 돌아가세요; 그리고 이제 막 시작해 근본부터 오류를 피하고 싶다면 초보자를 위한 10단계 를 따르세요. 환경을 표준화해 작은 오류를 장기적으로 줄이려면 Claude Code용 AgentKit 리뷰 를 살펴보세요.