GrepBoard/매뉴얼
47 편 ·

Claude Code 오류 문구별 조치

·Claude Code 2.1.302 · Ubuntu 24.04·7 단계

Claude Code 가 Invalid API key · Not logged in · 529 Overloaded · 연결 거부 · 인증서 오류를 낼 때, 문구로 원인을 찾아 환경 변수와 설정으로 고치는 순서입니다.

화면에 뜬 오류 문구를 아래 단계에서 찾아 조치합니다.

[1] 먼저 설치 상태를 봅니다. claude 가 안 뜨면 셸에서 claude doctor 를, 뜨면 세션 안의 /doctor 를 씁니다.

console
$ claude --version2.1.302 (Claude Code)$ claude doctorClaude Code doctor Running: npm-global (2.1.302)Platform: linux-x64Search: OK (bundled)Auto-updates: enabledAuto-update channel: latest No installation issues found.

[2] Not logged in · Please run /login 이면 로그인 정보가 없는 것입니다. 대화형 세션에서 /login 을 실행합니다.

console
$ claude -p hi --max-turns 1Not logged in · Please run /login

[3] Invalid API key · Fix external API key 이면 ANTHROPIC_API_KEY 에 든 값이 틀린 것입니다. 프로필에서 값의 출처를 찾고, 구독 로그인을 쓰려면 변수를 지웁니다.

console
$ ANTHROPIC_API_KEY=sk-ant-invalid claude -p hi --max-turns 1Invalid API key · Fix external API key$ grep -n ANTHROPIC_API_KEY ~/.zshrc ~/.bashrc ~/.profile$ unset ANTHROPIC_API_KEY

[4] API Error: Repeated 529 Overloaded errors 는 서버 쪽 용량 부족입니다. 사용량 한도와 무관합니다.

  • status.claude.com 에서 장애·용량 공지를 봅니다.
  • 몇 분 뒤 다시 시도합니다.
  • /model 로 다른 모델로 바꿉니다. 용량은 모델별로 집계됩니다. Opus is experiencing high load, please use /model to switch to Sonnet 같은 안내가 뜨기도 합니다.

[5] Connection refused — a firewall or proxy may be blocking it (ECONNREFUSED) 이면 프록시나 방화벽에서 막힌 것입니다. 사내 프록시를 쓴다면 HTTPS_PROXY 를 맞춥니다. 값은 http:// 로 시작해야 하며 SOCKS 는 지원하지 않습니다. 마지막 명령은 닿지 않는 프록시(127.0.0.1:9)로 오류를 재현합니다.

console
$ export HTTPS_PROXY=http://proxy.example.com:8080$ export NO_PROXY="localhost,example.com"$ HTTPS_PROXY=http://127.0.0.1:9 CLAUDE_CODE_MAX_RETRIES=1 claude -p hi --max-turns 1API Error: Connection refused — a firewall or proxy may be blocking it (ECONNREFUSED)

[6] 회사 프록시가 TLS 를 검사해 unable to get local issuer certificate · SELF_SIGNED_CERT_IN_CHAIN · SSL certificate verification failed 가 나오면 회사 루트 인증서를 신뢰시킵니다.

console
$ export NODE_EXTRA_CA_CERTS=/etc/ssl/certs/corp-ca.pem$ claude --debug

[7] 환경 변수를 매번 내보내기 싫으면 설정 파일의 env 에 넣습니다. 위치는 아래 순서로 우선합니다.

~/.claude/settings.json
{"env": {  "HTTPS_PROXY": "http://proxy.example.com:8080",  "NODE_EXTRA_CA_CERTS": "/etc/ssl/certs/corp-ca.pem"}}
  • 조직 관리 설정(managed settings) — 가장 우선
  • claude --settings — 그 세션만
  • .claude/settings.local.json — 이 프로젝트, 나만
  • .claude/settings.json — 이 프로젝트, 모두
  • ~/.claude/settings.json — 모든 프로젝트, 나만

#claude-code#troubleshooting