Claude Code 에러 총정리: command not found부터 인증·MCP·컨텍스트 한계까지 해결

며칠 전 새 맥북을 세팅하면서 Claude Code를 다시 깔았는데, 설치는 분명 끝났다는데 claude를 치니까 zsh: command not found: claude가 뜨더군요. "또 이거냐" 싶었습니다. 그 뒤로 SSH로 붙은 서버에서는 OAuth 코드가 자꾸 만료되고, MCP 서버는 에러 한 줄 없이 그냥 목록에 안 뜨고, 한참 작업하다 보니 /compact가 "Conversation too long"으로 거부당하는 데드락까지. 하루에 Claude Code가 막힐 수 있는 거의 모든 지점을 다 밟아본 셈입니다.

다행히 이 문제들은 대부분 패턴이 정해져 있습니다. 공식 문서와 GitHub 이슈트래커에 똑같은 사례가 반복적으로 올라오고, 진단의 80%는 명령어 하나로 끝납니다. 이 글에서는 제가 실제로 겪었고 검증한 순서대로, 설치 → 인증 → MCP → 컨텍스트 한계 → 저메모리 서버 OOM 5가지를 원인부터 단계별 해결까지 정리합니다.

먼저: 막히면 무조건 claude doctor부터

본론에 들어가기 전에 가장 중요한 습관 하나. 무엇이 안 되든 일단 진단부터 돌리세요.

claude doctor
# 대화 세션 안에서는 슬래시 커맨드로도 동일하게 동작
/doctor

claude doctor는 설치 경로, PATH 등록 상태, 인증 상태, 설정 파일 오류를 한 번에 스캔합니다. 경험상 설정 문제의 80% 정도는 여기서 바로 원인이 드러납니다. claude doctor(CLI 서브커맨드)와 /doctor(슬래시 커맨드)는 같은 진단을 가리키며 문서상 혼용됩니다.

트러블슈팅의 절반은 "추측하지 않기"입니다. 에러 메시지를 눈으로 읽고, claude doctor 출력을 읽고, 그다음에 손을 대세요. 묻지도 따지지도 않고 재설치부터 하면 멀쩡한 설치를 부수고 새 문제를 만듭니다.

1. 설치는 됐는데 command not found: claude

가장 흔한 첫 관문입니다.

zsh: command not found: claude
bash: claude: command not found
'claude' is not recognized as an internal or external command (Windows)

원인

네이티브 설치 시 바이너리는 정해진 위치에 놓입니다. macOS/Linux는 ~/.local/bin/claude, Windows는 %USERPROFILE%\.local\bin\claude.exe. 문제는 이 디렉터리가 셸 PATH에 등록돼 있지 않으면 셸이 명령을 찾지 못한다는 점입니다. 설치 실패가 아니라 경로 문제죠.

또 하나 자주 빠지는 함정: VS Code 확장만 설치한 경우입니다. 확장은 CLI를 확장 내부에 번들하기 때문에, ~/.local/bin에는 claude 바이너리가 아예 존재하지 않습니다. 그래서 터미널에서는 영영 못 찾습니다.

단계별 해결

1. 설치 자체가 됐는지 먼저 확인합니다.

# macOS / Linux
ls -la ~/.local/bin/claude

# Windows PowerShell
Test-Path "$env:USERPROFILE\.local\bin\claude.exe"

2. PATH에 들어있는지 확인합니다. 출력이 없으면 미등록입니다.

echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"

3. PATH에 추가합니다. zsh 기준입니다(bash는 ~/.bashrc 대상).

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Windows PowerShell은 사용자 환경변수에 추가한 뒤 터미널을 재시작합니다.

$currentPath = [Environment]::GetEnvironmentVariable('PATH','User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

4. 확인합니다.

claude --version

5. VS Code 확장만 깔았던 거라면, standalone 설치를 별도로 수행합니다.

curl -fsSL https://claude.ai/install.sh | bash

6. 그래도 이상하면 중복 설치가 원인일 수 있습니다. 네이티브 1개만 남기고 정리하세요.

which -a claude                                  # 어디에 몇 개 깔렸는지 확인
npm uninstall -g @anthropic-ai/claude-code       # npm 글로벌 제거
rm -rf ~/.claude/local                           # 레거시 설치 제거

여러 경로에 중복 설치돼 있으면 어느 게 먼저 잡히느냐에 따라 버전이 꼬이고 진단이 어려워집니다. 깨끗하게 하나만 남기는 게 정신 건강에 좋습니다.

2. 인증/로그인 실패 — OAuth 만료, 403, 그리고 API 키 충돌

설치를 넘기면 다음 관문은 인증입니다. 메시지가 세 종류쯤 됩니다.

OAuth error: Invalid code. Please make sure the full code was copied
API Error: 403 {"error":{"type":"forbidden","message":"Request not allowed"}}
API Error: 400 ... "This organization has been disabled"

원인 — 세 갈래로 나뉩니다

• (a) OAuth 코드 문제: 로그인 코드가 만료됐거나 복사하다 잘렸습니다. 특히 SSH/원격 환경에선 브라우저가 다른 머신에서 열려 콜백이 실패합니다.
• (b) 403 Forbidden: 구독 비활성, Console 역할(Claude Code·Developer) 미부여, 또는 프록시 간섭입니다.
• (c) "organization disabled" 충돌: 이게 진짜 함정인데요. 이전 직장·프로젝트에서 쓰던 ANTHROPIC_API_KEY가 셸 프로필에 그대로 남아 있어서, 구독 OAuth 자격증명을 덮어쓰는 경우입니다. 특히 -p 비대화 모드에서는 API 키가 항상 우선하기 때문에, 구독으로 쓰려는데 죽은 키가 끼어들어 조직이 비활성됐다는 엉뚱한 에러가 납니다.

단계별 해결

1. 기본 처방: 재로그인. 대부분 이걸로 풀립니다.

/logout
# Claude Code 종료 후
claude        # 재시작하면서 다시 인증

2. OAuth Invalid code: 브라우저가 안 열리면 로그인 프롬프트에서 c를 눌러 URL을 복사해 로컬 브라우저에 붙여넣고 빠르게 완료하세요(코드는 금방 만료됩니다). SSH/WSL 환경이라면 표준입력으로 코드를 받는 방식이 더 안정적입니다.

claude auth login

3. 403 Forbidden: Pro/Max 사용자는 claude.ai/settings에서 구독이 활성인지 확인합니다. Console(팀) 사용자는 관리자에게 'Claude Code' 또는 'Developer' 역할 부여를 요청하세요. 프록시 환경이면 네트워크 설정을 점검합니다.

4. "organization disabled" 충돌 — 구독을 쓰려면 죽은 키를 치워야 합니다.

unset ANTHROPIC_API_KEY
claude

임시방편이 아니라 영구히 없애려면 프로필에서 해당 줄을 지웁니다. ~/.zshrc, ~/.bashrc, ~/.profile(Windows는 $PROFILE)에서 export ANTHROPIC_API_KEY=... 줄을 제거하세요.

5. 지금 어떤 인증을 쓰고 있는지 확인하려면:

/status

6. macOS에서 자꾸 로그아웃된다면 Keychain 잠김 문제일 수 있습니다. claude doctor로 점검하고, 필요시 수동으로 잠금을 풉니다.

security unlock-keychain ~/Library/Keychains/login.keychain-db

7. 토큰이 비정상적으로 자주 만료되면 시스템 시계가 틀어졌는지 확인하세요. 토큰 검증은 타임스탬프에 의존합니다.

3. MCP 서버 연결 실패 — 에러도 없이 그냥 안 뜬다

MCP(Model Context Protocol) 서버를 붙일 때 가장 짜증나는 건, 에러 한 줄 없이 그냥 서버 목록에 안 나타나는 무경고 실패(silent fail)입니다.

(에러 없이 서버 목록에 안 뜸 / silent fail)
MCP server failed to connect
(경로에 공백·특수문자가 있을 때 연결 실패)

원인 — 흔한 근본 원인 리스트

1. stdout 오염: stdio 트랜스포트에서 서버가 로그를 stdout에 쓰면, 프로토콜 스트림이 오염돼 연결이 끊깁니다. 디버그 출력은 반드시 stderr로 가야 합니다. (가장 흔한 원인)
2. Windows에서 cmd /c 래퍼 누락/오용
3. 잘못된 command/args 또는 오래된(stale) PATH
4. Claude Code를 공백·특수문자가 포함된 경로에서 실행
5. 만료·누락된 자격증명
6. VS Code 확장 기동 시 타이밍 이슈로 인한 무경고 실패

단계별 해결

1. 먼저 진단부터.

claude doctor

2. MCP 설정의 command와 args를 그대로 복사해 터미널에서 직접 실행해 보세요. 이게 핵심입니다. Claude Code가 삼켜버린 진짜 에러 메시지가 터미널에는 그대로 나옵니다.

# 예: 설정에 적힌 그대로 손으로 실행
npx -y @some/mcp-server --flag value

3. 서버 코드가 stdout에 로그를 찍는지 점검하고, 모든 로그/디버그 출력을 stderr로 바꿉니다. 직접 만든 MCP 서버라면 십중팔구 여기가 범인입니다.

4. Windows라면 npx류 실행에 cmd /c 래퍼가 필요한지 확인하고, command/args 형식을 MCP 문서 규격에 맞춥니다.

5. 깨끗한 경로에서 기동합니다. 서버의 cwd만 깨끗해도 실행 디렉터리(Claude Code를 띄운 디렉터리)에 공백이 있으면 실패하는 사례가 보고됐습니다(GitHub #19518).

6. VS Code 확장에서 무경고 실패라면, 명령 팔레트에서 Developer: Reload Window를 실행하세요. 두 번째 시도에 연결되는 경우가 일관되게 보고됩니다. 타이밍 이슈로 추정됩니다.

7. 서버가 요구하는 API 키·토큰이 만료·누락 아닌지 마지막으로 확인합니다.

MCP는 stdio 위에서 JSON-RPC가 흐르는 구조라, "출력을 함부로 stdout에 흘리지 않는다"는 원칙만 지켜도 절반은 막힙니다. 이쪽 디버깅에 익숙하지 않다면 블로그의 다른 AI 도구 트러블슈팅 글도 함께 참고하세요.

4. 컨텍스트 한계 — /compact가 "Conversation too long"으로 죽을 때

긴 작업을 하다 보면 만나는 마지막 벽입니다.

Conversation too long        (/compact 실행 시)
context window limit          (표시 사용량이 20%인데도 발생)
usage limit reached           (리셋 시각 안내)

원인

• (a) /compact 데드락: /compact는 대화를 요약 전용 소형 모델로 보내 압축합니다. 그런데 메시지 토큰이 일정 임계값(보고된 사례 기준 약 78k)을 넘으면, 주 모델(예: 200k)에는 여유가 있어도 요약 모델의 컨텍스트를 초과해 실패합니다. 정작 압축이 가장 필요한 순간에 압축이 막히는 데드락이죠.
• (b) 숨은 컨텍스트: 시스템 프롬프트·툴 정의 같은 보이지 않는 토큰이 실제 사용량을 부풀려, 표시값이 낮아도(20% 등) 한계 에러가 나는 경우가 특정 버전에서 보고됐습니다(회귀).
• (c) usage limit: 구독/API 사용량 한도 도달.

버전 의존 주의: 위 '약 78k 요약 모델 한계'와 '20% 표시에도 context limit(특정 버전 회귀)'는 특정 시점의 구현 세부/회귀입니다. 정확한 임계값은 추정이 섞여 있고, 현재 최신 버전에서는 수정·변동됐을 수 있습니다. 재현 시 반드시 버전을 확인하세요.

단계별 해결

1. 선제적으로 압축하는 습관을 들이세요. 한계에 도달하기 전, 긴 스레드 보존이 필요할 때 미리 /compact를 겁니다. 새 작업을 시작할 때는 아예 비웁니다.

/compact     # 한계 도달 전 미리
/clear       # 새 작업 시작 시 컨텍스트 비우기

2. 이미 "Conversation too long"으로 막혔다면, 현재로선 회피책이 정답입니다. 핵심 내용을 수동으로 메모해 두고 /clear로 탈출하세요.

3. 더 가벼운 모델로 전환해 여유를 확보하고, 불필요한 대용량 파일 읽기/붙여넣기를 줄입니다.

/model       # 가벼운 모델로 전환

4. 표시 사용량은 낮은데 한계가 난다면, 버전 회귀 가능성이 있으니 최신 버전으로 업데이트 후 재시도합니다.

5. usage limit reached는 안내된 리셋 시각까지 기다리거나, API 과금 사용자라면 사용량을 확인하고 플랜/결제를 점검합니다.

/cost

6. 장기 작업은 CLAUDE.md나 메모리에 진행 맥락을 적어두세요. 그러면 /clear로 컨텍스트를 비운 뒤에도 복원할 수 있습니다. 이건 회피책이 아니라 좋은 작업 설계입니다.

5. 저메모리 Linux 서버에서 설치 중 Killed (OOM)

마지막으로, 서버 환경에서만 나는 문제입니다.

bash: line 142: ... Killed   "$binary_path" install

원인

Claude Code는 공식 문서 기준 최소 4GB 가용 RAM을 요구합니다. RAM이 부족한 VPS/클라우드 인스턴스에서는 Linux OOM killer가 설치 프로세스를 강제 종료합니다. 특히 Docker에서 root로 / 경로에서 설치하면 전체 파일시스템을 스캔하면서 메모리를 과소비해 hang/OOM을 유발합니다.

단계별 해결

1. 스왑(swap)을 먼저 확보하고 설치를 재시도합니다.

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

2. 설치 전 다른 프로세스를 종료해 메모리를 확보하고, 가능하면 더 큰 인스턴스(최소 4GB RAM 권장)를 쓰세요.

3. Docker는 Dockerfile에서 작업 디렉터리를 잡아 전체 FS 스캔을 회피합니다. 필요하면 메모리 한도도 올립니다.

WORKDIR /tmp

docker build --memory=4g .

참고: 이 부분은 저희 운영 환경에도 직접 닿습니다. promptarchitect.ai.kr이 올라가 있는 NCP 1GB 서버처럼 저사양 환경에 Claude Code 자체를 설치하려 하면 동일한 OOM이 날 수 있습니다. swap 2GB 선확보가 사실상 필수입니다. 다만 'NCP 1GB에서 OOM' 부분은 공식 문서의 OOM 메커니즘을 이 환경에 적용한 추론이며, 직접 검증한 수치는 아닙니다.

Do's / Don'ts 정리

구분	Do (권장)	Don't (피하기)
진단	막히면 claude doctor / /doctor 먼저	원인 확인 없이 곧장 재설치
설치	네이티브 1개만 남기고 PATH 등록	npm·VS Code·레거시 중복 방치
인증	안 풀리면 /logout 후 재로그인	죽은 ANTHROPIC_API_KEY를 프로필에 방치
구독 사용	unset ANTHROPIC_API_KEY로 키 충돌 제거	-p 모드에서 키가 구독을 덮어쓰는 걸 무시
MCP	설정의 command/args를 터미널에서 직접 실행	무경고 실패를 추측으로만 디버깅
MCP 로그	디버그 출력은 전부 stderr로	stdout에 로그를 찍어 프로토콜 오염
컨텍스트	한계 전 /compact, 새 작업은 /clear	꽉 찬 뒤에야 /compact 시도(데드락)
서버	설치 전 swap 2GB 확보	1GB 인스턴스에서 무방비 설치

실전 팁 3가지

1. 셸 프로필 청소를 정기적으로. ANTHROPIC_API_KEY 같은 환경변수가 예전 프로젝트의 잔재로 남아 있으면, 가장 디버깅하기 어려운 인증 충돌을 일으킵니다. 이직·프로젝트 이동 시 ~/.zshrc를 한 번 훑으세요.
2. MCP 서버를 만들 땐 stdout을 신성시하세요. stdio 트랜스포트에서 stdout은 오직 프로토콜 전용입니다. print()나 console.log()로 디버깅하던 습관이 곧장 무경고 연결 실패로 이어집니다. 로그는 무조건 stderr로.
3. 장기 작업은 컨텍스트가 휘발될 것을 전제로 설계하세요. 진행 상황·결정 사항을 CLAUDE.md에 적어두면, /clear나 세션 종료 뒤에도 맥락을 복원할 수 있습니다. 컨텍스트 한계를 '에러'가 아니라 '관리 대상'으로 다루는 관점 전환이 핵심입니다.

마무리

Claude Code에서 막히는 지점은 결국 다섯 군데로 수렴합니다. 설치 직후 PATH 문제(command not found), 인증 충돌(OAuth·403·API 키), MCP 무경고 연결 실패(stdout 오염이 주범), 컨텍스트 한계(/compact 데드락), 그리고 저메모리 서버 OOM. 그리고 이 모든 진단의 출발점은 언제나 claude doctor 한 줄입니다.

다음에 무언가 막히면 (1) claude doctor로 진단하고, (2) 이 글에서 해당 증상의 단계를 따라가고, (3) 그래도 안 되면 에러 메시지 그대로 공식 문서나 이슈트래커에서 검색하세요. 똑같은 사례가 거의 항상 먼저 보고돼 있습니다.

LLM API 자체의 과부하·재시도 처리가 궁금하다면 Claude API 529 Overloaded 에러 핸들링 글을, 다른 AI 도구 문제 해결은 팁 모음을 이어서 보시길 권합니다.

참고 자료

• Claude Code 공식 설치 트러블슈팅 문서 — 에러 메시지·해결법 원문
• Anthropic Claude Code GitHub 이슈트래커 — MCP silent fail(#25751), 경로 공백(#19518), /compact 'Conversation too long'(#23751 등) 사례
• Model Context Protocol 공식 문서 — MCP 서버 설정 규격

본문의 일부 임계값(요약 모델 ~78k, 특정 버전의 컨텍스트 회귀 등)은 보고된 시점 기준이며 최신 버전에서 변동됐을 수 있습니다. 에러 메시지 문자열은 로케일에 따라 한국어로 표시될 수 있어 영어 원문 그대로 표기했습니다.