설치 및 로그인 문제 해결

설치가 실패하거나 로그인할 수 없는 경우 아래에서 오류를 찾으세요. Claude Code가 작동한 후 런타임 문제의 경우 문제 해결을 참조하세요. 설정이 적용되지 않거나 hooks가 실행되지 않는 등의 구성 문제의 경우 구성 디버깅을 참조하세요.

오류 찾기

표시되는 오류 메시지 또는 증상을 수정 사항과 일치시키세요:

표시되는 내용	해결책
`command not found: claude` 또는 `'claude' is not recognized`	PATH 수정
`syntax error near unexpected token '<'`	설치 스크립트가 HTML 반환
`curl: (56) Failure writing output to destination`	연결성 확인 또는 대체 설치 프로그램 사용
Linux에서 설치 중 `Killed`	저메모리 서버에 스왑 공간 추가
`TLS connect error` 또는 `SSL/TLS secure channel`	CA 인증서 업데이트
`Failed to fetch version` 또는 다운로드 서버에 도달할 수 없음	네트워크 및 프록시 설정 확인
`irm is not recognized` 또는 `&& is not valid`	셸에 맞는 명령 사용
`'bash' is not recognized as the name of a cmdlet`	Windows 설치 프로그램 명령 사용
`Claude Code on Windows requires git-bash`	Git Bash 설치 또는 구성
`Claude Code does not support 32-bit Windows`	Windows PowerShell 열기, x86 항목 아님
`Error loading shared library`	시스템에 맞는 잘못된 바이너리 변형
`Illegal instruction`	아키텍처 또는 CPU 명령어 세트 불일치
WSL에서 `cannot execute binary file: Exec format error`	WSL1 네이티브 바이너리 회귀
PowerShell 설치 프로그램이 완료되지만 `claude`를 찾을 수 없거나 이전 버전 표시	터미널 다시 시작 및 PATH 확인
macOS에서 `dyld: cannot load`, `dyld: Symbol not found` 또는 `Abort trap`	바이너리 비호환성
`Invoke-Expression: Missing argument in parameter list`	설치 스크립트가 HTML 반환
`App unavailable in region`	Claude Code는 귀국에서 사용할 수 없습니다. 지원되는 국가를 참조하세요.
`unable to get local issuer certificate`	회사 CA 인증서 구성
`OAuth error` 또는 `403 Forbidden`	인증 수정
`Could not load the default credentials` 또는 `Could not load credentials from any providers`	Bedrock, Vertex 또는 Foundry 자격증명
`ChainedTokenCredential authentication failed` 또는 `CredentialUnavailableError`	Bedrock, Vertex 또는 Foundry 자격증명
`API Error: 500`, `529 Overloaded`, `429` 또는 위에 나열되지 않은 기타 4xx 및 5xx 오류	오류 참조를 참조하세요

문제가 나열되지 않은 경우 아래의 진단 검사를 수행하여 원인을 좁혀보세요.

터미널을 완전히 건너뛰고 싶다면 Claude Code Desktop 앱을 사용하여 그래픽 인터페이스를 통해 Claude Code를 설치하고 사용할 수 있습니다. macOS 또는 Windows용으로 다운로드하고 명령줄 설정 없이 코딩을 시작하세요.

진단 검사 실행

네트워크 연결성 확인

설치 프로그램은 downloads.claude.ai에서 다운로드합니다. 도달할 수 있는지 확인하세요:

curl -sI https://downloads.claude.ai/claude-code-releases/latest

HTTP/2 200 줄은 서버에 도달했음을 의미합니다. 출력이 없거나 Could not resolve host 또는 연결 시간 초과가 표시되면 네트워크가 연결을 차단하고 있습니다. 일반적인 원인:

downloads.claude.ai를 차단하는 회사 방화벽 또는 프록시
지역 네트워크 제한: VPN 또는 대체 네트워크 시도
TLS/SSL 문제: 시스템의 CA 인증서를 업데이트하거나 HTTPS_PROXY가 구성되어 있는지 확인

회사 프록시 뒤에 있는 경우 설치하기 전에 HTTPS_PROXY 및 HTTP_PROXY를 프록시 주소로 설정하세요. 프록시 URL을 모르는 경우 IT 팀에 문의하거나 브라우저의 프록시 설정을 확인하세요. 이 예제는 두 프록시 변수를 설정한 다음 프록시를 통해 설치 프로그램을 실행합니다:

macOS/Linux
Windows PowerShell

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash

$env:HTTP_PROXY = 'http://proxy.example.com:8080'
$env:HTTPS_PROXY = 'http://proxy.example.com:8080'
irm https://claude.ai/install.ps1 | iex

PATH 확인

설치가 성공했지만 claude를 실행할 때 command not found 또는 not recognized 오류가 발생하면 설치 디렉토리가 PATH에 없습니다. 셸은 PATH에 나열된 디렉토리에서 프로그램을 검색하고 설치 프로그램은 macOS/Linux에서 ~/.local/bin/claude에 또는 Windows에서 %USERPROFILE%\.local\bin\claude.exe에 claude를 배치합니다. PATH 항목을 나열하고 local/bin을 필터링하여 설치 디렉토리가 PATH에 있는지 확인하세요:

macOS/Linux
Windows PowerShell
Windows CMD

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

이것이 /Users/you/.local/bin 또는 /home/you/.local/bin을 인쇄하면 디렉토리가 PATH에 있으므로 충돌하는 설치 확인으로 건너뛸 수 있습니다. 출력이 없으면 셸 구성에 추가하세요.macOS의 기본값인 Zsh의 경우:

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

대부분의 Linux 배포판의 기본값인 Bash의 경우:

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

또는 터미널을 닫았다가 다시 여세요.수정이 작동했는지 확인하세요:

claude --version

$env:PATH -split ';' | Select-String '\.local\\bin'

출력이 없으면 설치 디렉토리를 사용자 PATH에 추가하세요:

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

변경 사항이 적용되려면 터미널을 다시 시작하세요.수정이 작동했는지 확인하세요:

claude --version

echo %PATH% | findstr /i "local\bin"

출력이 없으면 시스템 설정을 열고 환경 변수로 이동한 다음 %USERPROFILE%\.local\bin을 사용자 PATH 변수에 추가하세요. 터미널을 다시 시작하세요.수정이 작동했는지 확인하세요:

claude --version

충돌하는 설치 확인

여러 Claude Code 설치로 인해 버전 불일치 또는 예기치 않은 동작이 발생할 수 있습니다. 설치된 항목을 확인하세요:

macOS/Linux
Windows PowerShell

PATH에서 찾은 모든 claude 바이너리를 나열하세요:

which -a claude

이것이 아무것도 인쇄하지 않으면 아직 PATH에 claude가 없습니다. PATH 확인으로 돌아가세요.claude 바이너리가 올 수 있는 세 위치를 확인하세요. ~/.local/bin/claude는 네이티브 설치 프로그램이고 ~/.claude/local/은 Claude Code의 이전 버전에서 생성한 레거시 로컬 npm 설치이며 npm 글로벌 목록은 -g 설치를 표시합니다:

ls -la ~/.local/bin/claude

ls -la ~/.claude/local/

npm -g ls @anthropic-ai/claude-code 2>/dev/null

PATH에서 찾은 모든 claude 바이너리를 나열하세요:

where.exe claude

네이티브 설치 프로그램이 바이너리를 배치했는지 확인하세요:

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

여러 설치를 찾으면 하나만 유지하세요. macOS/Linux의 ~/.local/bin/claude 또는 Windows의 %USERPROFILE%\.local\bin\claude.exe에서의 네이티브 설치가 권장됩니다. 추가 항목을 제거하세요: npm 글로벌 설치 제거:

npm uninstall -g @anthropic-ai/claude-code

레거시 로컬 npm 설치 제거:

rm -rf ~/.claude/local

Windows에서 PowerShell을 사용하세요:

Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\local"

macOS에서 Homebrew 설치 제거. claude-code@latest cask를 설치한 경우 해당 이름으로 대체하세요:

brew uninstall --cask claude-code

Windows에서 WinGet 설치 제거:

winget uninstall Anthropic.ClaudeCode

디렉토리 권한 확인

설치 프로그램은 macOS 및 Linux의 ~/.local/bin/ 및 ~/.claude/에 대한 쓰기 액세스가 필요합니다. Windows에서 설치 위치는 %USERPROFILE% 아래에 있으며 기본적으로 사용자가 쓸 수 있으므로 이 섹션은 거의 적용되지 않습니다. 디렉토리가 쓸 수 있는지 확인하세요:

test -w ~/.local/bin && echo "writable" || echo "not writable"
test -w ~/.claude && echo "writable" || echo "not writable"

디렉토리를 쓸 수 없으면 설치 디렉토리를 만들고 사용자를 소유자로 설정하세요:

sudo mkdir -p ~/.local/bin
sudo chown -R $(whoami) ~/.local

바이너리 작동 확인

claude --version이 버전을 인쇄하지만 claude가 시작 시 충돌하거나 중단되면 이 검사를 실행하여 원인을 좁혀보세요. claude --version이 command not found를 표시하면 먼저 PATH 확인으로 이동하세요. 아래 명령은 claude가 PATH에 있다고 가정합니다. 바이너리가 존재하고 실행 가능한지 확인하세요:

ls -la "$(command -v claude)"

Windows에서 PowerShell을 사용하세요:

Get-Command claude | Select-Object Source

Linux에서 누락된 공유 라이브러리를 확인하세요. ldd가 누락된 라이브러리를 표시하면 시스템 패키지를 설치해야 할 수 있습니다. Alpine Linux 및 기타 musl 기반 배포판의 경우 Alpine Linux 설정을 참조하세요.

ldd "$(command -v claude)" | grep "not found"

바이너리가 실행될 수 있는지 확인하세요:

claude --version

일반적인 설치 문제

이는 가장 자주 발생하는 설치 문제와 해결책입니다.

설치 스크립트가 셸 스크립트 대신 HTML 반환

설치 명령을 실행할 때 다음 오류 중 하나가 표시될 수 있습니다:

bash: line 1: syntax error near unexpected token `<'
bash: line 1: `<!DOCTYPE html>'

PowerShell에서 동일한 문제는 다음과 같이 나타납니다:

Invoke-Expression: Missing argument in parameter list.

이는 설치 URL이 설치 스크립트 대신 HTML 페이지를 반환했음을 의미합니다. HTML 페이지에 “App unavailable in region”이 표시되면 Claude Code는 귀국에서 사용할 수 없습니다. 지원되는 국가를 참조하세요. 그렇지 않으면 네트워크 문제, 지역 라우팅 또는 일시적인 서비스 중단으로 인해 발생할 수 있습니다. 해결책:

대체 설치 방법 사용: macOS에서 Homebrew를 통해 설치:
```
brew install --cask claude-code
```
Windows에서 WinGet을 통해 설치:
```
winget install Anthropic.ClaudeCode
```
몇 분 후 다시 시도: 문제는 종종 일시적입니다. 기다렸다가 원래 명령을 다시 시도하세요.

설치 후 `command not found: claude`

설치가 완료되었지만 claude가 작동하지 않습니다. 정확한 오류는 플랫폼에 따라 다릅니다:

플랫폼	오류 메시지
macOS	`zsh: command not found: claude`
Linux	`bash: claude: command not found`
Windows CMD	`'claude' is not recognized as an internal or external command`
PowerShell	`claude : The term 'claude' is not recognized as the name of a cmdlet`

이는 설치 디렉토리가 셸의 검색 경로에 없음을 의미합니다. 각 플랫폼의 수정 사항은 PATH 확인을 참조하세요.

`curl: (56) Failure writing output to destination`

curl ... | bash 명령은 스크립트를 다운로드하고 Bash에 파이프하여 실행합니다. 이 오류는 스크립트 다운로드가 완료되기 전에 연결이 끊어졌음을 의미합니다. 일반적인 원인은 네트워크 중단, 다운로드가 중간에 차단되거나 시스템 리소스 제한입니다. 해결책:

네트워크 안정성 확인: Claude Code 바이너리는 downloads.claude.ai에서 호스팅됩니다. 도달할 수 있는지 테스트하세요:
```
curl -sI https://downloads.claude.ai/claude-code-releases/latest
```
HTTP/2 200 줄은 서버에 도달했으며 원래 실패가 일시적이었음을 의미합니다. 설치 명령을 다시 시도하세요. Could not resolve host 또는 연결 시간 초과가 표시되면 네트워크가 다운로드를 차단하고 있습니다.

대체 설치 방법 시도: macOS에서:

brew install --cask claude-code

Windows에서:

winget install Anthropic.ClaudeCode

TLS 또는 SSL 연결 오류

curl: (35) TLS connect error, schannel: next InitializeSecurityContext failed 또는 PowerShell의 Could not establish trust relationship for the SSL/TLS secure channel과 같은 오류는 TLS 핸드셰이크 실패를 나타냅니다. 해결책:

시스템 CA 인증서 업데이트: Ubuntu/Debian에서:
```
sudo apt-get update && sudo apt-get install ca-certificates
```
macOS에서 시스템 curl은 Keychain 신뢰 저장소를 사용합니다. macOS 자체를 업데이트하면 루트 인증서가 업데이트됩니다.

Windows에서 설치 프로그램을 실행하기 전에 PowerShell에서 TLS 1.2 활성화:

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
irm https://claude.ai/install.ps1 | iex

프록시 또는 방화벽 간섭 확인: TLS 검사를 수행하는 회사 프록시는 unable to get local issuer certificate 및 SELF_SIGNED_CERT_IN_CHAIN을 포함한 이러한 오류를 유발할 수 있습니다. 설치 단계의 경우 curl을 회사 CA 번들로 가리키세요 --cacert:
```
curl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash
```
설치된 Claude Code 자체의 경우 NODE_EXTRA_CA_CERTS를 설정하여 API 요청이 동일한 번들을 신뢰하도록 하세요:
```
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
```
인증서 파일이 없으면 IT 팀에 문의하세요. 프록시가 원인인지 확인하기 위해 직접 연결에서 시도할 수도 있습니다.
Windows에서 인증서 해지 확인 무시 CRYPT_E_NO_REVOCATION_CHECK (0x80092012) 또는 CRYPT_E_REVOCATION_OFFLINE (0x80092013)이 표시되면. 이는 curl이 서버에 도달했지만 네트워크가 인증서 해지 조회를 차단함을 의미하며, 이는 회사 방화벽 뒤에서 일반적입니다. 설치 명령에 --ssl-revoke-best-effort를 추가하세요:
```
curl --ssl-revoke-best-effort -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
```
또는 curl을 완전히 피하는 winget install Anthropic.ClaudeCode로 설치하세요.

`Failed to fetch version from downloads.claude.ai`

설치 프로그램이 다운로드 서버에 도달할 수 없습니다. 이는 일반적으로 downloads.claude.ai가 네트워크에서 차단됨을 의미합니다. 해결책:

직접 연결성 테스트:

curl -sI https://downloads.claude.ai/claude-code-releases/latest

프록시 뒤에 있는 경우 HTTPS_PROXY를 설정하여 설치 프로그램이 프록시를 통해 라우팅할 수 있도록 하세요. 자세한 내용은 프록시 구성을 참조하세요.
```
export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash
```
제한된 네트워크에 있는 경우 다른 네트워크 또는 VPN을 시도하거나 대체 설치 방법을 사용하세요: macOS에서:
```
brew install --cask claude-code
```
Windows에서:
```
winget install Anthropic.ClaudeCode
```

Windows에서 잘못된 설치 명령

'irm' is not recognized, The token '&&' is not valid 또는 'bash' is not recognized as the name of a cmdlet이 표시되면 다른 셸 또는 운영 체제의 설치 명령을 복사했습니다.

irm 인식 안 됨: CMD에 있고 PowerShell이 아닙니다. 두 가지 옵션이 있습니다: 시작 메뉴에서 “PowerShell”을 검색하여 PowerShell을 열고 원래 설치 명령을 실행하세요:
```
irm https://claude.ai/install.ps1 | iex
```
또는 CMD에 머물러 있고 CMD 설치 프로그램을 대신 사용하세요:
```
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
```
&& 유효하지 않음: PowerShell에 있지만 CMD 설치 프로그램 명령을 실행했습니다. PowerShell 설치 프로그램을 사용하세요:
```
irm https://claude.ai/install.ps1 | iex
```
bash 인식 안 됨: Windows에서 macOS/Linux 설치 프로그램을 실행했습니다. 대신 PowerShell 설치 프로그램을 사용하세요:
```
irm https://claude.ai/install.ps1 | iex
```

저메모리 Linux 서버에서 설치 중단

VPS 또는 클라우드 인스턴스에서 설치 중에 Killed가 표시되면:

Setting up Claude Code...
Installing Claude Code native build latest...
bash: line 142: 34803 Killed    "$binary_path" install ${TARGET:+"$TARGET"}

Linux OOM killer는 시스템이 메모리 부족으로 인해 프로세스를 종료했습니다. Claude Code는 최소 4GB의 사용 가능한 RAM이 필요합니다. 해결책:

서버의 RAM이 제한된 경우 스왑 공간 추가. 스왑은 디스크 공간을 오버플로우 메모리로 사용하여 낮은 물리적 RAM으로도 설치를 완료할 수 있게 합니다. 2GB 스왑 파일을 만들고 활성화하세요:
```
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
```
그런 다음 설치를 다시 시도하세요:
```
curl -fsSL https://claude.ai/install.sh | bash
```
설치하기 전에 다른 프로세스를 닫아 메모리를 확보하세요.
가능하면 더 큰 인스턴스 사용. Claude Code는 최소 4GB의 RAM이 필요합니다.

Docker에서 설치 중단

Docker 컨테이너에서 Claude Code를 설치할 때 root로 /에 설치하면 중단될 수 있습니다. 해결책:

설치 프로그램을 실행하기 전에 작업 디렉토리 설정. /에서 실행하면 설치 프로그램이 전체 파일 시스템을 스캔하여 과도한 메모리 사용을 유발합니다. WORKDIR을 설정하면 스캔이 작은 디렉토리로 제한됩니다:
```
WORKDIR /tmp
RUN curl -fsSL https://claude.ai/install.sh | bash
```
Docker 메모리 제한 증가 Docker Desktop을 사용하는 경우:
```
docker build --memory=4g .
```

Claude Desktop이 Windows에서 `claude` 명령 무시

Claude Desktop의 이전 버전을 설치한 경우 WindowsApps 디렉토리에 Claude.exe를 등록할 수 있으며, 이는 Claude Code CLI보다 PATH 우선순위를 가집니다. claude를 실행하면 CLI 대신 Desktop 앱이 열립니다. Claude Desktop을 최신 버전으로 업데이트하여 이 문제를 해결하세요.

Windows에서 Claude Code는 Git Bash 필요

Windows의 Claude Code는 셸 명령을 실행하기 위해 Git Bash를 제공하는 Git for Windows가 필요합니다. Git이 설치되지 않은 경우 git-scm.com/downloads/win에서 다운로드하세요. 설정 중에 “Add to PATH”를 선택하세요. 설치 후 터미널을 다시 시작하세요. Git이 이미 설치되어 있지만 Claude Code가 찾을 수 없으면 settings.json 파일에서 경로를 설정하세요:

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

Git이 다른 곳에 설치된 경우 PowerShell에서 where.exe git을 실행하여 경로를 찾고 해당 디렉토리의 bin\bash.exe 경로를 사용하세요.

Claude Code는 32비트 Windows를 지원하지 않음

Windows는 시작 메뉴에 두 개의 PowerShell 항목을 포함합니다: Windows PowerShell 및 Windows PowerShell (x86). x86 항목은 32비트 프로세스로 실행되며 64비트 머신에서도 이 오류를 트리거합니다. 어느 경우인지 확인하려면 오류를 생성한 동일한 창에서 이를 실행하세요:

[Environment]::Is64BitOperatingSystem

이것이 True를 인쇄하면 운영 체제는 정상입니다. 창을 닫고 x86 접미사 없이 Windows PowerShell을 열고 설치 명령을 다시 실행하세요. 이것이 False를 인쇄하면 32비트 Windows 버전을 사용 중입니다. Claude Code는 64비트 운영 체제가 필요합니다. 시스템 요구사항을 참조하세요.

Linux musl 또는 glibc 바이너리 불일치

설치 후 libstdc++.so.6 또는 libgcc_s.so.1과 같은 누락된 공유 라이브러리에 대한 오류가 표시되면 설치 프로그램이 시스템에 맞는 잘못된 바이너리 변형을 다운로드했을 수 있습니다.

Error loading shared library libstdc++.so.6: No such file or directory

이는 musl 크로스 컴파일 패키지가 설치된 glibc 기반 시스템에서 발생할 수 있으며, 설치 프로그램이 시스템을 musl로 잘못 감지하게 합니다. 해결책:

시스템이 어느 libc를 사용하는지 확인:
```
ldd --version 2>&1 | head -1
```
GNU libc 또는 GLIBC를 언급하는 출력은 glibc를 의미합니다. musl을 언급하는 출력은 musl을 의미합니다.
glibc에 있지만 musl 바이너리를 받은 경우 설치를 제거하고 다시 설치하세요. https://downloads.claude.ai/claude-code-releases/{VERSION}/manifest.json의 매니페스트를 사용하여 올바른 바이너리를 수동으로 다운로드할 수도 있습니다. ldd --version 및 ls /lib/libc.musl*의 출력과 함께 GitHub 이슈를 제출하세요.
실제로 musl에 있는 경우 Alpine Linux와 같이 필요한 패키지를 설치하세요:
```
apk add libgcc libstdc++ ripgrep
```

`Illegal instruction`

claude를 실행하거나 설치 프로그램이 Illegal instruction을 인쇄하면 네이티브 바이너리는 프로세서가 지원하지 않는 CPU 명령어를 사용합니다. 두 가지 서로 다른 원인이 있습니다. 아키텍처 불일치. 설치 프로그램이 잘못된 바이너리를 다운로드했습니다. 예를 들어 ARM 서버의 x86. macOS 또는 Linux에서 uname -m으로 확인하거나 PowerShell에서 $env:PROCESSOR_ARCHITECTURE로 확인하세요. 결과가 받은 바이너리와 일치하지 않으면 출력과 함께 GitHub 이슈를 제출하세요. 구형 CPU의 누락된 명령어 세트. 아키텍처는 올바르지만 여전히 Illegal instruction이 표시되면 CPU에 바이너리가 필요로 하는 AVX 또는 다른 명령어가 없을 가능성이 높습니다. 이는 대략 2013년 이전의 Intel 및 AMD 프로세서에 영향을 미칩니다. 현재 네이티브 바이너리 해결 방법이 없습니다. 이슈 #50384를 추적하고 Linux에서 cat /proc/cpuinfo | grep "model name" | head -1 또는 macOS에서 sysctl -n machdep.cpu.brand_string의 CPU 모델을 보고할 때 포함하세요. 대체 설치 방법은 동일한 네이티브 바이너리를 다운로드하며 어느 원인도 해결하지 않습니다.

macOS에서 `dyld: cannot load`

설치 중에 dyld: cannot load, dyld: Symbol not found 또는 Abort trap: 6이 표시되면 바이너리는 macOS 버전 또는 하드웨어와 호환되지 않습니다.

dyld: cannot load 'claude-2.1.42-darwin-x64' (load command 0x80000034 is unknown)
Abort trap: 6

libicucore를 참조하는 Symbol not found 오류는 macOS 버전이 바이너리가 지원하는 것보다 오래되었음을 나타냅니다:

dyld: Symbol not found: _ubrk_clone
  Referenced from: claude-darwin-x64 (which was built for Mac OS X 13.0)
  Expected in: /usr/lib/libicucore.A.dylib

해결책:

macOS 버전 확인: Claude Code는 macOS 13.0 이상이 필요합니다. Apple 메뉴를 열고 이 Mac에 관하여를 선택하여 버전을 확인하세요.
이전 버전을 사용 중인 경우 macOS 업데이트. 바이너리는 이전 macOS 버전이 지원하지 않는 로드 명령 및 시스템 라이브러리를 사용합니다. Homebrew와 같은 대체 설치 방법은 동일한 바이너리를 다운로드하며 이 오류를 해결하지 않습니다.

WSL1에서 `Exec format error`

WSL에서 claude를 실행하면 cannot execute binary file: Exec format error가 인쇄되면 WSL1에 있으며 이슈 #38788에서 추적되는 알려진 네이티브 바이너리 회귀를 겪고 있습니다. 바이너리의 프로그램 헤더가 WSL1의 로더가 처리할 수 없는 방식으로 변경되었습니다. 가장 깔끔한 수정은 PowerShell에서 배포판을 WSL2로 변환하는 것입니다:

wsl --set-version <DistroName> 2

WSL1에 머물러야 하는 경우 동적 링커를 통해 바이너리를 호출하세요. WSL 내 ~/.bashrc에 이 함수를 추가하고 홈 디렉토리가 다르면 경로를 바꾸세요:

claude() {
  /lib64/ld-linux-x86-64.so.2 "$(readlink -f "$HOME/.local/bin/claude")" "$@"
}

그런 다음 source ~/.bashrc를 실행하고 claude를 다시 시도하세요.

WSL에서 npm 설치 오류

이 문제는 WSL 내에서 npm install -g로 Claude Code를 설치한 경우 적용됩니다. 네이티브 설치 프로그램을 사용한 경우 이 섹션을 건너뛰세요. OS 또는 플랫폼 감지 문제. npm이 설치 중에 플랫폼 불일치를 보고하면 WSL이 Windows npm을 선택하고 있을 가능성이 높습니다. 먼저 npm config set os linux를 실행한 다음 npm install -g @anthropic-ai/claude-code --force로 설치하세요. sudo를 사용하지 마세요. claude 실행 시 exec: node: not found. WSL 환경이 Node.js의 Windows 설치를 사용하고 있을 가능성이 높습니다. which npm 및 which node로 확인하세요: /mnt/c/로 시작하는 경로는 Windows 바이너리이고 Linux 경로는 /usr/로 시작합니다. 이를 수정하려면 Linux 배포판의 패키지 관리자 또는 nvm을 통해 Node를 설치하세요. nvm 버전 충돌. WSL과 Windows 모두에 nvm이 설치되어 있으면 WSL에서 Node 버전을 전환하면 WSL이 기본적으로 Windows PATH를 가져오고 Windows nvm이 우선순위를 가지기 때문에 중단될 수 있습니다. 가장 일반적인 원인은 nvm이 셸에 로드되지 않는 것입니다. nvm 로더를 ~/.bashrc 또는 ~/.zshrc에 추가하세요:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

또는 현재 세션에서 로드하세요:

source ~/.nvm/nvm.sh

nvm이 로드되었지만 Windows 경로가 여전히 우선순위를 가지면 Linux Node 경로를 명시적으로 앞에 추가하세요:

export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"

appendWindowsPath = false를 통해 Windows PATH 가져오기를 비활성화하지 마세요. WSL에서 Windows 실행 파일을 호출하는 기능이 중단됩니다. 마찬가지로 Windows 개발에 사용하는 경우 Windows에서 Node.js를 제거하지 마세요.

설치 중 권한 오류

네이티브 설치 프로그램이 권한 오류로 실패하면 대상 디렉토리를 쓸 수 없을 수 있습니다. 디렉토리 권한 확인을 참조하세요. 이전에 npm으로 설치했고 npm 특정 권한 오류를 겪고 있으면 네이티브 설치 프로그램으로 전환하세요:

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

npm 설치 후 네이티브 바이너리를 찾을 수 없음

@anthropic-ai/claude-code npm 패키지는 @anthropic-ai/claude-code-darwin-arm64와 같은 플랫폼별 선택적 종속성을 통해 네이티브 바이너리를 가져옵니다. 설치 후 claude를 실행하면 Could not find native binary package "@anthropic-ai/claude-code-<platform>"이 인쇄되면 다음 원인을 확인하세요:

선택적 종속성이 비활성화됨. npm 설치 명령에서 --omit=optional을 제거하고 pnpm에서 --no-optional을 제거하고 yarn에서 --ignore-optional을 제거하고 .npmrc가 optional=false를 설정하지 않는지 확인하세요. 그런 다음 다시 설치하세요. 네이티브 바이너리는 선택적 종속성으로만 제공되므로 건너뛰면 JavaScript 폴백이 없습니다.
지원되지 않는 플랫폼. 미리 빌드된 바이너리는 darwin-arm64, darwin-x64, linux-x64, linux-arm64, linux-x64-musl, linux-arm64-musl, win32-x64 및 win32-arm64에 대해 게시됩니다. Claude Code는 다른 플랫폼에 대한 바이너리를 제공하지 않습니다. 시스템 요구사항을 참조하세요.
회사 npm 미러가 플랫폼 패키지를 누락함. 레지스트리가 메타 패키지 외에도 8개의 @anthropic-ai/claude-code-* 플랫폼 패키지를 모두 미러링하는지 확인하세요.

--ignore-scripts로 설치하면 이 오류가 트리거되지 않습니다. 바이너리를 제자리에 연결하는 postinstall 단계를 건너뛰므로 Claude Code는 각 시작 시 플랫폼 바이너리를 찾아 생성하는 래퍼로 폴백합니다. 이는 작동하지만 더 느리게 시작됩니다. 직접 실행을 위해 스크립트를 활성화하여 다시 설치하세요.

로그인 및 인증

이 섹션은 로그인 실패, OAuth 오류 및 토큰 문제를 다룹니다.

로그인 재설정

로그인이 실패하고 원인이 명확하지 않으면 깨끗한 재인증이 대부분의 경우를 해결합니다:

/logout을 실행하여 완전히 로그아웃
Claude Code 닫기
claude로 다시 시작하고 인증 프로세스 완료

브라우저가 로그인 중에 자동으로 열리지 않으면 c를 눌러 OAuth URL을 클립보드에 복사한 다음 수동으로 브라우저에 붙여넣으세요. 이는 URL이 좁은 또는 SSH 터미널에서 줄을 넘어 래핑되고 직접 클릭할 수 없을 때도 작동합니다.

OAuth 오류: 유효하지 않은 코드

OAuth error: Invalid code. Please make sure the full code was copied가 표시되면 로그인 코드가 만료되었거나 복사-붙여넣기 중에 잘렸습니다. 해결책:

Enter를 눌러 다시 시도하고 브라우저가 열린 후 빠르게 로그인 완료
브라우저가 자동으로 열리지 않으면 c를 입력하여 전체 URL 복사
원격/SSH 세션을 사용하는 경우 브라우저가 잘못된 머신에서 열릴 수 있습니다. 터미널에 표시된 URL을 복사하고 로컬 브라우저에서 대신 열어보세요.

로그인 후 403 Forbidden

로그인 후 API Error: 403 {"error":{"type":"forbidden","message":"Request not allowed"}}가 표시되면:

Claude Pro/Max 사용자: claude.ai/settings에서 구독이 활성화되어 있는지 확인
Anthropic Console 사용자: 계정에 “Claude Code” 또는 “Developer” 역할이 있는지 확인. 관리자는 Anthropic Console의 설정 → 멤버에서 이를 할당합니다.
프록시 뒤에 있음: 회사 프록시가 API 요청을 방해할 수 있습니다. 프록시 설정은 네트워크 구성을 참조하세요.

이 조직은 활성 구독으로 비활성화되었습니다

활성 Claude 구독이 있음에도 불구하고 API Error: 400 ... "This organization has been disabled"가 표시되면 ANTHROPIC_API_KEY 환경 변수가 구독을 무시하고 있습니다. 이는 이전 고용주 또는 프로젝트의 이전 API 키가 여전히 셸 프로필에 설정되어 있을 때 일반적으로 발생합니다. ANTHROPIC_API_KEY가 있고 승인한 경우 Claude Code는 구독의 OAuth 자격증명 대신 해당 키를 사용합니다. -p 플래그를 사용한 비대화형 모드에서는 키가 있을 때 항상 사용됩니다. 전체 해결 순서는 인증 우선순위를 참조하세요. 대신 구독을 사용하려면 환경 변수를 설정 해제하고 셸 프로필에서 제거하세요:

unset ANTHROPIC_API_KEY
claude

~/.zshrc, ~/.bashrc 또는 ~/.profile에서 export ANTHROPIC_API_KEY=... 줄을 확인하고 변경을 영구적으로 만들려면 제거하세요. Windows에서 $PROFILE의 PowerShell 프로필과 ANTHROPIC_API_KEY의 사용자 환경 변수를 확인하세요. Claude Code 내에서 /status를 실행하여 어느 인증 방법이 활성화되어 있는지 확인하세요.

WSL2에서 OAuth 로그인 실패

WSL2의 브라우저 기반 로그인은 두 가지 방식으로 실패할 수 있습니다: WSL이 Windows 브라우저를 열 수 없거나 터미널이 붙여넣은 인증 코드를 수락하지 않습니다. 브라우저가 열리지 않으면 BROWSER 환경 변수를 Windows 브라우저 경로로 설정하세요:

export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
claude

또는 로그인 프롬프트에서 c를 눌러 OAuth URL을 복사하고 Windows 브라우저에 직접 붙여넣으세요. 브라우저가 열리지만 코드를 터미널에 다시 붙여넣으면 아무것도 하지 않으면 터미널의 붙여넣기 바인딩이 프롬프트에 도달하지 않을 가능성이 높습니다. 터미널의 대체 붙여넣기 바로 가기를 시도하세요. 종종 Windows Terminal에서 우클릭 또는 Shift+Insert이거나 대화형 UI 외부에서 로그인을 실행하세요:

claude auth login

이 폴백은 네이티브 Windows 또는 대화형 프롬프트에 코드를 붙여넣기가 실패하는 모든 터미널에도 적용됩니다.

로그인하지 않음 또는 토큰 만료

Claude Code가 세션 후 다시 로그인하도록 요청하면 OAuth 토큰이 만료되었을 수 있습니다. /login을 실행하여 다시 인증하세요. 이것이 자주 발생하면 토큰 검증이 올바른 타임스탬프에 따라 달라지므로 시스템 시계가 정확한지 확인하세요. macOS에서 Keychain이 잠겨 있거나 암호가 계정 암호와 동기화되지 않으면 로그인이 실패할 수도 있으며, 이는 Claude Code가 자격증명을 저장하지 못하게 합니다. claude doctor를 실행하여 Keychain 액세스를 확인하세요. Keychain을 수동으로 잠금 해제하려면 security unlock-keychain ~/Library/Keychains/login.keychain-db를 실행하세요. 잠금 해제가 도움이 되지 않으면 Keychain Access를 열고 login keychain을 선택한 다음 편집 > Keychain “login”의 암호 변경을 선택하여 계정 암호와 다시 동기화하세요.

Bedrock, Vertex 또는 Foundry 자격증명이 로드되지 않음

Claude Code를 클라우드 공급자를 사용하도록 구성했고 Bedrock에서 Could not load credentials from any providers, Vertex에서 Could not load the default credentials 또는 Foundry에서 ChainedTokenCredential authentication failed가 표시되면 클라우드 공급자 CLI가 현재 셸에서 인증되지 않았을 가능성이 높습니다. Bedrock의 경우 AWS 자격증명이 유효한지 확인하세요:

aws sts get-caller-identity

Vertex AI의 경우 ANTHROPIC_VERTEX_PROJECT_ID 및 CLOUD_ML_REGION이 셸에 설정되어 있는지 확인한 다음 애플리케이션 기본 자격증명을 설정하세요:

gcloud auth application-default login

Microsoft Foundry의 경우 ANTHROPIC_FOUNDRY_API_KEY가 설정되어 있는지 확인하거나 Azure CLI로 로그인하여 기본 자격증명 체인이 계정을 찾을 수 있도록 하세요:

az login

자격증명이 터미널에서 작동하지만 VS Code 또는 JetBrains 확장에서 작동하지 않으면 IDE 프로세스가 셸 환경을 상속하지 않았을 가능성이 높습니다. IDE의 자체 설정에서 공급자 환경 변수를 설정하거나 이미 내보낸 터미널에서 IDE를 시작하세요. 전체 공급자 설정은 Amazon Bedrock, Google Vertex AI 또는 Microsoft Foundry를 참조하세요.

여전히 막혔습니다

위의 어느 것도 문제를 해결하지 못하면:

GitHub 저장소에서 알려진 문제를 확인하거나 운영 체제, 실행한 설치 명령 및 전체 오류 출력과 함께 새 문제를 열어보세요
claude --version이 작동하지만 다른 것이 잘못되면 claude doctor를 실행하여 자동화된 진단 보고서를 받으세요
세션을 시작할 수 있으면 Claude Code 내에서 /feedback을 사용하여 문제를 보고하세요

에이전트

도구 및 플러그인

자동화

문제 해결

설치 및 로그인 문제 해결

오류 찾기

진단 검사 실행

네트워크 연결성 확인

PATH 확인

충돌하는 설치 확인

디렉토리 권한 확인

바이너리 작동 확인

일반적인 설치 문제

설치 스크립트가 셸 스크립트 대신 HTML 반환

설치 후 `command not found: claude`

`curl: (56) Failure writing output to destination`

TLS 또는 SSL 연결 오류

`Failed to fetch version from downloads.claude.ai`

Windows에서 잘못된 설치 명령

저메모리 Linux 서버에서 설치 중단

Docker에서 설치 중단

Claude Desktop이 Windows에서 `claude` 명령 무시

Windows에서 Claude Code는 Git Bash 필요

Claude Code는 32비트 Windows를 지원하지 않음

Linux musl 또는 glibc 바이너리 불일치

`Illegal instruction`

macOS에서 `dyld: cannot load`

WSL1에서 `Exec format error`

WSL에서 npm 설치 오류

설치 중 권한 오류

npm 설치 후 네이티브 바이너리를 찾을 수 없음

로그인 및 인증

로그인 재설정

OAuth 오류: 유효하지 않은 코드

로그인 후 403 Forbidden

이 조직은 활성 구독으로 비활성화되었습니다

WSL2에서 OAuth 로그인 실패

로그인하지 않음 또는 토큰 만료

Bedrock, Vertex 또는 Foundry 자격증명이 로드되지 않음

여전히 막혔습니다

에이전트

도구 및 플러그인

자동화

문제 해결

Documentation Index

​오류 찾기

​진단 검사 실행

​네트워크 연결성 확인

​PATH 확인

​충돌하는 설치 확인

​디렉토리 권한 확인

​바이너리 작동 확인

​일반적인 설치 문제

​설치 스크립트가 셸 스크립트 대신 HTML 반환

​설치 후 command not found: claude

​curl: (56) Failure writing output to destination

​TLS 또는 SSL 연결 오류

​Failed to fetch version from downloads.claude.ai

​Windows에서 잘못된 설치 명령

​저메모리 Linux 서버에서 설치 중단

​Docker에서 설치 중단

​Claude Desktop이 Windows에서 claude 명령 무시

​Windows에서 Claude Code는 Git Bash 필요

​Claude Code는 32비트 Windows를 지원하지 않음

​Linux musl 또는 glibc 바이너리 불일치

​Illegal instruction

​macOS에서 dyld: cannot load

​WSL1에서 Exec format error

​WSL에서 npm 설치 오류

​설치 중 권한 오류

​npm 설치 후 네이티브 바이너리를 찾을 수 없음

​로그인 및 인증

​로그인 재설정

​OAuth 오류: 유효하지 않은 코드

​로그인 후 403 Forbidden

​이 조직은 활성 구독으로 비활성화되었습니다

​WSL2에서 OAuth 로그인 실패

​로그인하지 않음 또는 토큰 만료

​Bedrock, Vertex 또는 Foundry 자격증명이 로드되지 않음

​여전히 막혔습니다

오류 찾기

진단 검사 실행

네트워크 연결성 확인

PATH 확인

충돌하는 설치 확인

디렉토리 권한 확인

바이너리 작동 확인

일반적인 설치 문제

설치 스크립트가 셸 스크립트 대신 HTML 반환

설치 후 `command not found: claude`

`curl: (56) Failure writing output to destination`

TLS 또는 SSL 연결 오류

`Failed to fetch version from downloads.claude.ai`

Windows에서 잘못된 설치 명령

저메모리 Linux 서버에서 설치 중단

Docker에서 설치 중단

Claude Desktop이 Windows에서 `claude` 명령 무시

Windows에서 Claude Code는 Git Bash 필요

Claude Code는 32비트 Windows를 지원하지 않음

Linux musl 또는 glibc 바이너리 불일치

`Illegal instruction`

macOS에서 `dyld: cannot load`

WSL1에서 `Exec format error`

WSL에서 npm 설치 오류

설치 중 권한 오류

npm 설치 후 네이티브 바이너리를 찾을 수 없음

로그인 및 인증

로그인 재설정

OAuth 오류: 유효하지 않은 코드

로그인 후 403 Forbidden

이 조직은 활성 구독으로 비활성화되었습니다

WSL2에서 OAuth 로그인 실패

로그인하지 않음 또는 토큰 만료

Bedrock, Vertex 또는 Foundry 자격증명이 로드되지 않음

여전히 막혔습니다