본문으로 건너뛰기

에러 메시지 카탈로그

Claude Code 사용 중 에러 메시지를 만났을 때 무엇이 잘못됐고 어떻게 회복하는지 정리합니다. 설치·로그인 단계 에러(command not found·PATH·OAuth login 실패 등)는 레벨 1 설치 챕터를, 모델 협업 행동 패턴 트러블은 레벨 3 트러블슈팅을 참고합니다.

팁

정확한 에러 분류와 최신 해결법은 공식 에러 레퍼런스가 베이스입니다. 본 챕터는 한국어 시청자가 자주 만나는 케이스를 추려 정리합니다.

자동 재시도가 먼저 일어난다​

서버 에러, 529 과부하, 요청 타임아웃, 일시 429 throttle, 끊긴 연결 — Claude Code는 모두 최대 10회 지수 백오프로 자동 재시도한 뒤에 에러를 표시합니다. 화면에 보이는 Retrying in Ns · attempt x/y 카운트다운이 그 표시.

에러가 화면에 떴다 = 자동 재시도가 이미 다 소진됐다는 뜻입니다. 두 환경 변수로 동작 조정:

변수기본값효과
CLAUDE_CODE_MAX_RETRIES10재시도 횟수. 스크립트에선 낮추면 실패가 빨리 드러남. 긴 incident 견디려면 올림
API_TIMEOUT_MS600000요청당 타임아웃 (ms). 느린 네트워크·프록시면 올림

서버 에러 — 일시 장애​

API Error: 500 Internal server error
API Error: Repeated 529 Overloaded errors
Request timed out

자동 재시도 후에도 안 풀린 케이스. 나의 프롬프트·설정·계정 문제 아님.

해결:

  • status.claude.com 활성 incident 확인
  • 잠시 후 다시 요청 — 이전 메시지가 대화에 남아 있으니 긴 프롬프트면 try again만 입력해도 됨
  • 한 모델만 부하 심하면 /model로 다른 모델로 전환 (capacity는 모델별 추적)

사용 한도 — 본인 플랜이 다 찼다​

You've hit your session limit · resets 3:45pm
You've hit your weekly limit · resets Mon 12:00am
You've hit your Opus limit · resets 3:45pm

구독 플랜의 rolling 사용 한도 소진. 표시된 리셋 시각까지 차단.

해결:

  • 리셋 시각 대기
  • /usage로 플랜 한도·리셋 시점 확인
  • Pro·Max는 /usage-credits로 추가 사용량 구매. Team·Enterprise는 관리자에게 요청
  • 한도 도달 전 미리 보려면 커스텀 statusline에 rate_limits 필드 추가 (Velog 일지 #50 statusline 참고)

인증 — 자격 증명 문제​

환경변수 stale로 구독이 무시되는 케이스​

Your ANTHROPIC_API_KEY belongs to a disabled organization · Unset the environment variable to use your other credentials

가장 자주 만나는 함정. 이전 직장·프로젝트에서 설정한 ANTHROPIC_API_KEY가 shell profile에 남아 있고, 그 키가 비활성 조직에 속한 경우. 환경변수가 /login 구독보다 우선이라 Pro·Max 구독이 있어도 stale 키가 먼저 쓰임.

해결:

unset ANTHROPIC_API_KEY
claude

~/.zshrc·~/.bashrc·~/.profile에서 export ANTHROPIC_API_KEY=... 라인을 영구 제거. Windows는 PowerShell profile ($PROFILE)과 사용자 환경 변수 확인. 그 후 /status로 현재 활성 자격 증명 확인.

로그인 만료​

OAuth token revoked · Please run /login
OAuth token has expired · Please run /login

/login으로 재인증. 반복되면 /logout 먼저 → /login. 시스템 시계 부정확하면 토큰 검증 실패하니 시계 확인.

네트워크 — 연결 불가​

Unable to connect to API. Check your internet connection
fetch failed
SSL certificate verification failed

회사 프록시·VPN·firewall이 흔한 원인.

해결:

  • 같은 쉘에서 curl -I https://api.anthropic.com 시도 (Windows PowerShell은 curl.exe로 — Invoke-WebRequest alias 회피)
  • 회사 프록시면 HTTPS_PROXY 설정 후 Claude Code 시작
  • LLM gateway 통한 라우팅이면 ANTHROPIC_BASE_URL 설정
  • TLS 가로채는 corporate proxy면 NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem 환경변수로 회사 CA 번들 지정. NODE_TLS_REJECT_UNAUTHORIZED=0은 절대 금지 (인증서 검증 자체를 끔)

요청 에러 — 프롬프트가 너무 길거나 잘못된 상태​

프롬프트가 컨텍스트 윈도우를 넘김​

Prompt is too long

해결:

  • /compact로 이전 turn 요약 → 공간 확보. 또는 /clear로 새 시작
  • /context로 시스템 프롬프트·메모리·MCP 도구·메시지가 각각 얼마 차지하는지 확인 (Velog 일지 #38 참고)
  • 안 쓰는 MCP 서버는 /mcp disable <name>으로 도구 정의 제거
  • 거대한 CLAUDE.md는 경로 한정 룰로 분리해서 필요할 때만 로드

/compact 자체가 실패​

Error during compaction: Conversation too long. Press esc twice to go up a few messages and try again.

/compact가 요약을 만들 공간조차 없는 경우. Esc 두 번으로 몇 turn 뒤로 가서 최근 메시지 일부 떨어뜨린 뒤 다시 /compact. 그래도 안 되면 /clear로 새 세션 → 이전 대화는 /resume으로 복원 가능.

이미지·PDF 크기 초과​

Image was too large. Double press esc to go back and try again with a smaller image.
PDF too large (max 100 pages, 32 MB).

오류 발생 시 이미지가 대화 history에 남아 다음 메시지도 같은 에러로 막힘. Esc 두 번으로 해당 turn 뒤로 가서 작은 이미지로 재첨부. 단일 이미지는 가장 긴 변 8000px, 여러 이미지면 2000px 이하.

도구 호출 흐름이 꼬임​

API Error: 400 due to tool use concurrency issues. Run /rewind to recover the conversation.

도구 호출이 중간에 끊겨 history가 일관성 잃은 경우. /rewind 또는 Esc 두 번으로 체크포인트 시점 직전으로 되감기 후 진행. (체크포인트는 레벨 2 체크포인팅 참고)

응답 품질이 갑자기 떨어졌다​

에러는 없는데 답변이 평소보다 약해진 경우. 모델이 조용히 바뀌진 않음 — 원인은 거의 대화 상태입니다.

체크 순서:

  • /model — 의도한 모델인지 확인. 이전 /model 선택이나 ANTHROPIC_MODEL 환경변수가 작은 모델로 묶어둔 경우 있음
  • /effort — 현재 reasoning 레벨 확인. 어려운 디버깅·설계는 올림. 모델별 기본값이 다르니 최대치라 단정 X (Velog 일지 #44 참고)
  • /context — 윈도우 차 있는 정도 확인. 가득 차면 /compact 또는 /clear
  • /doctor — 비대해진 CLAUDE.md·subagent 정의 검출

응답이 잘못된 turn에선 수정 메시지로 고치기보다 /rewind로 되감기 후 더 구체적 프롬프트로 재시도 권장. in-thread 수정은 잘못된 시도를 컨텍스트에 남겨 이후 답도 그쪽으로 끌리게 함.

Auto Mode — 분류기가 판단 실패​

<model> is temporarily unavailable, so auto mode cannot determine the safety of ...
Auto mode could not evaluate this action and is blocking it for safety
Auto mode classifier transcript exceeded context window

Auto Mode (Velog 일지 #43 참고)가 자동 승인 결정 못 한 경우. Working directory 안 read·search·edit는 분류기 건너뛰니 계속 동작.

해결:

  • 첫 두 메시지 = 잠시 후 재시도, Claude도 같은 메시지 보고 보통 자동 재시도
  • 세 번째 메시지 = 인터랙티브 세션이면 보통 권한 프롬프트로 fallback. non-interactive mode (-p)에선 중단 — /compact로 줄여야

진단·제보​

본 페이지에 없는 에러나 위 해결법이 안 통하면:

  • /feedback — Claude Code 안에서 실행. transcript와 설명을 Anthropic에 전송, GitHub issue prefill 제안. Bedrock·Vertex·Foundry 같은 third-party provider면 로컬 archive로 저장
  • /doctor — 로컬 설정 문제 자동 진단
  • status.claude.com — 활성 incident 확인
  • GitHub issues — 기존 보고 검색

정리​

카테고리첫 액션
서버 에러 (5xx·529·timeout)status.claude.com → 잠시 후 재시도 → /model 전환
사용 한도/usage 확인 → 리셋 대기 또는 /usage-credits
인증 (stale env)unset ANTHROPIC_API_KEY → shell profile 영구 제거 → /status 확인
네트워크curl -I https://api.anthropic.com → 프록시 설정·CA 번들
프롬프트 길이/compact → 안 되면 Esc 두 번 → /clear
도구 흐름 꼬임/rewind
응답 품질 저하/model → /effort → /context → /rewind 후 재요청
Auto Mode 실패잠시 재시도 → 권한 프롬프트로 fallback → 필요 시 /compact

다음 레벨: ⚙️ 레벨 3 — 중급

최종 수정: 에