[Claude Code 번역] Claude Code Troubleshooting (Claude Code Troubleshooting)

출처: https://docs.anthropic.com/en/docs/claude-code/troubleshooting

개요

Claude Code 설치 및 사용 중 자주 발생하는 문제에 대한 해결 방법을 안내합니다.

일반적인 설치 문제

Linux 권한 문제

npm으로 Claude Code를 설치할 때, npm 글로벌 프리픽스가 사용자 쓰기 권한이 없는 경로(예: /usr, /usr/local)로 설정되어 있으면 권한 오류가 발생할 수 있습니다.

권장 해결책: 사용자 쓰기 가능한 npm 프리픽스 설정

가장 안전한 방법은 홈 디렉터리 내에 npm 글로벌 패키지 경로를 설정하는 것입니다.

# 기존 글로벌 패키지 목록 저장
npm list -g --depth=0 > ~/npm-global-packages.txt

# 글로벌 패키지용 디렉터리 생성
mkdir -p ~/.npm-global

# npm 프리픽스 경로 변경
npm config set prefix ~/.npm-global

# 사용 중인 셸에 따라 환경 변수 추가
# (예: ~/.bashrc, ~/.zshrc, ~/.profile 등)
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc

# 변경 사항 적용
source ~/.bashrc

# Claude Code를 새 경로에 설치
npm install -g @anthropic-ai/claude-code

# 필요하다면 이전 글로벌 패키지 재설치
# ~/npm-global-packages.txt 참고

이 방법은 시스템 디렉터리 권한을 변경하지 않고, 보안상 안전하며, 글로벌 npm 패키지를 위한 별도 경로를 제공합니다.

시스템 복구: 시스템 디렉터리 권한을 잘못 변경한 경우

만약 sudo chown -R $USER:$(id -gn) /usr && sudo chmod -R u+w /usr 등으로 시스템 디렉터리 권한을 변경해 시스템이 손상되었다면(예: sudo: /usr/bin/sudo must be owned by uid 0 and have the setuid bit set 오류), 다음과 같이 복구할 수 있습니다.

Ubuntu/Debian 복구 방법

부팅 시 SHIFT를 눌러 GRUB 메뉴 진입
"Advanced options for Ubuntu/Debian" 선택
복구 모드 진입
"Drop to root shell prompt" 선택
파일시스템을 쓰기 가능으로 마운트
```
mount -o remount,rw /
```

권한 복구

# 루트 소유권 복구
chown -R root:root /usr
chmod -R 755 /usr
# /usr/local은 사용자 소유로
chown -R YOUR_USERNAME:YOUR_USERNAME /usr/local
# 주요 바이너리 setuid 비트 복구
chmod u+s /usr/bin/sudo
chmod 4755 /usr/bin/sudo
chmod u+s /usr/bin/su
chmod u+s /usr/bin/passwd
chmod u+s /usr/bin/newgrp
chmod u+s /usr/bin/gpasswd
chmod u+s /usr/bin/chsh
chmod u+s /usr/bin/chfn
# sudo 설정 복구
chown root:root /usr/libexec/sudo/sudoers.so
chmod 4755 /usr/libexec/sudo/sudoers.so
chown root:root /etc/sudo.conf
chmod 644 /etc/sudo.conf

패키지 재설치(선택)

dpkg --get-selections > /tmp/installed_packages.txt
awk '{print $1}' /tmp/installed_packages.txt | xargs -r apt-get install --reinstall -y

재부팅
```
reboot
```

라이브 USB 복구 방법

복구 모드가 동작하지 않는다면 라이브 USB로 부팅 후 아래 절차를 따르세요.

라이브 USB로 부팅
시스템 파티션 확인
```
lsblk
```

시스템 파티션 마운트

sudo mount /dev/sdXY /mnt  # sdXY는 실제 파티션명으로 대체

별도 부트 파티션이 있다면 추가 마운트
```
sudo mount /dev/sdXZ /mnt/boot  # 필요시
```

chroot로 시스템 진입

# Ubuntu/Debian
sudo chroot /mnt
# Arch 계열
sudo arch-chroot /mnt

위 Ubuntu/Debian 복구 6~8단계 진행

복구 후에는 위 권장 방법대로 사용자 쓰기 가능한 npm 프리픽스를 설정하세요.

자동 업데이트 문제

Claude Code가 자동으로 업데이트되지 않는 경우, npm 글로벌 프리픽스 권한 문제일 수 있습니다. 위 권장 해결책을 적용하세요.

자동 업데이트를 비활성화하려면 다음 명령을 사용하세요.

claude config set -g autoUpdaterStatus disabled

권한 및 인증 문제

반복되는 권한 승인 프롬프트

동일한 명령에 대해 반복적으로 권한 승인을 요청받는 경우, 특정 도구를 승인 목록에 추가할 수 있습니다.

# npm test를 승인 없이 실행
claude config add allowedTools "Bash(npm test)"

# npm test 및 하위 명령 전체 승인
claude config add allowedTools "Bash(npm test:*)"

인증 문제

인증 관련 문제가 발생하면:

/logout 명령으로 완전히 로그아웃
Claude Code 종료
claude로 재시작 후 인증 절차 진행

문제가 계속된다면 아래 명령으로 인증 정보를 삭제 후 재로그인하세요.

rm -rf ~/.config/claude-code/auth.json
claude

성능 및 안정성

CPU/메모리 사용량이 높을 때

Claude Code는 대부분의 개발 환경에서 잘 동작하지만, 대규모 코드베이스 처리 시 리소스 사용량이 높아질 수 있습니다. 성능 문제가 있다면:

/compact 명령으로 컨텍스트 크기 정기적으로 축소
주요 작업 전후 Claude Code 재시작
대용량 빌드 디렉터리는 .gitignore에 추가

명령이 멈추거나 응답이 없는 경우

Ctrl+C로 현재 작업 취소 시도
그래도 응답이 없으면 터미널을 종료 후 재시작

JetBrains(예: IntelliJ, PyCharm) 터미널에서 ESC 키가 동작하지 않을 때

JetBrains 터미널에서 ESC 키가 Claude Code 작업 취소로 동작하지 않는 경우, JetBrains 기본 단축키와 충돌 때문일 수 있습니다.

해결 방법:

Settings → Tools → Terminal 이동
"Override IDE Shortcuts" 옆의 "Configure terminal keybindings" 클릭
"Switch focus to Editor" 단축키를 찾아 삭제

이렇게 하면 ESC 키가 Claude Code 작업 취소에 정상 동작합니다.

추가 지원 받기

위 내용에 없는 문제가 발생하면:

Claude Code 내 /bug 명령으로 직접 문제 보고
GitHub 저장소에서 이슈 확인
/doctor 명령으로 설치 상태 점검

저작자표시 (새창열림)

개요