클로드 코드 왕초보 가이드 9편 — 이런 에러 나왔어요, 당황하지 마세요 2026

터미널에 빨간 글씨가 뜨면 심장이 한 번 쿵 합니다. "뭘 잘못한 거지?" 하는 생각이 먼저 듭니다.
다행히 Claude Code에서 만나는 에러 대부분은 패턴이 정해져 있습니다. 7가지만 알면 90%는 스스로 해결됩니다.

저도 처음 Claude Code를 깔았을 때 command not found가 뜨고 멘붕이 왔습니다. 코딩을 전혀 몰랐으니 에러 메시지 자체가 외국어였습니다. 그런데 몇 번 겪다 보니 깨달았습니다. 에러는 "고장"이 아니라 "안내문"입니다. 뭘 고치면 되는지 알려주는 겁니다.

에러 1 — "command not found: claude"

Claude Code를 설치하고 신나게 claude를 입력했는데 이런 메시지가 뜹니다.

bash: command not found: claude

컴퓨터가 "claude라는 프로그램을 못 찾겠다"고 말하는 겁니다. 설치가 안 된 건 아닙니다. 터미널이 설치된 위치를 아직 인식하지 못하는 상태입니다.

해결법

터미널을 완전히 닫고 새로 엽니다. 설치 직후에는 경로 정보가 갱신되지 않은 상태입니다. 새 터미널을 열면 대부분 해결됩니다.
그래도 안 되면 재설치합니다.

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

설치 과정이 기억나지 않는다면 3편 설치 가이드를 다시 확인해보세요.

에러 2~4 — 로그인, 속도, 지시 무시 문제

에러 2: 로그인이 안 됩니다

claude를 실행하면 브라우저에서 인증하라는 메시지가 뜹니다. 그런데 브라우저가 자동으로 안 열리거나, 열려도 인증이 완료되지 않을 때가 있습니다.

1 인증 URL 직접 복사

터미널에 표시된 URL을 마우스로 드래그해서 복사한 뒤, 브라우저 주소창에 직접 붙여넣으세요. 자동 실행이 안 될 뿐이지 URL 자체는 유효합니다.

2 그래도 안 되면 로그아웃 후 재시도

/logout

Claude Code 안에서 위 명령어를 입력하면 기존 인증 정보가 초기화됩니다. 그 다음 claude를 다시 실행하면 처음부터 인증 과정이 시작됩니다.

에러 3: 응답이 너무 느립니다

AI가 30초 넘게 생각만 하고 있다면, 대화가 너무 길어져서 처리할 양이 많아진 겁니다. 8편에서 다뤘던 컨텍스트 윈도우 문제입니다.

/compact — 대화 내용을 압축해서 처리량을 줄입니다.
/clear — 대화를 완전히 초기화합니다. 새 출발이 필요할 때 씁니다.

에러 4: 원하는 대로 안 해줍니다

AI가 엉뚱한 결과를 내놓는 건 대부분 지시가 모호했기 때문입니다. "대충 해줘"라고 하면 AI도 대충 합니다.

Before / After 비교

구분	지시 방식
Before (모호)	이 파일 좀 고쳐줘
After (구체적)	index.html 파일에서 제목을 "클로드 코드 가이드"로 바꾸고, 본문 첫 문단 아래에 날짜를 추가해줘

반복적으로 같은 규칙을 적용해야 한다면: 7편에서 다뤘던 CLAUDE.md 파일에 규칙을 적어두세요. 매번 말하지 않아도 AI가 자동으로 참고합니다.

에러 5~7 — 파일 수정, 기억, 한글 문제

에러 5: 파일을 잘못 수정했습니다

AI가 파일을 수정했는데 결과가 영 아닙니다. 원래 상태로 되돌리고 싶습니다. 당황해서 터미널을 닫지 마세요. Claude Code에는 되돌리기 기능이 있습니다.

1 Esc 두 번 — 되감기

Esc 키를 두 번 누르면 AI가 방금 한 작업을 되돌립니다. 파일 수정 전 상태로 복원됩니다. Ctrl+Z 같은 역할입니다.

2 Shift+Tab — 계획 모드

AI가 바로 실행하지 않고, 먼저 "이렇게 할 건데 괜찮습니까?"라고 계획을 보여주는 모드입니다. 중요한 파일을 수정할 때는 이 모드를 켜두면 실수를 미리 잡을 수 있습니다.

핵심: 되감기(Esc 두 번)와 계획 모드(Shift+Tab)만 기억하면 파일 수정 실수가 두렵지 않습니다. 실수해도 복구할 수 있다는 게 포인트입니다.

에러 6: 이전 내용을 기억 못합니다

분명 5분 전에 설명한 건데 AI가 "무슨 말씀이신지 모르겠습니다"라고 반응합니다. 8편에서 자세히 다뤘지만 핵심만 정리하면 이렇습니다.

/compact — 대화 압축. 공간 확보 후 다시 시도.
새 대화 시작 — claude를 다시 입력해서 깨끗한 상태에서 시작.
claude --continue — 직전 대화를 이어가고 싶을 때.

대화가 길어질수록 AI의 기억 공간이 줄어듭니다. 30분 이상 작업했다면 한 번쯤 /compact를 실행하는 습관을 들이세요.

에러 7: 한글이 깨집니다

AI가 만든 파일을 열어보니 한글이 ????나 �로 표시됩니다. 인코딩 문제입니다.

파일 인코딩을 UTF-8로 설정하세요. VS Code 기준으로 하단 상태바에서 인코딩 표시를 클릭하면 변경할 수 있습니다.
터미널은 VS Code 내장 터미널을 추천합니다. Windows 기본 명령 프롬프트(cmd)는 한글 인코딩 문제가 자주 발생합니다. VS Code 터미널이나 Windows Terminal을 쓰면 대부분 해결됩니다.

그래도 안 될 때 — 마지막 수단 2가지

위 7가지를 다 시도했는데도 문제가 해결되지 않을 때가 있습니다. 그때 쓰는 마지막 카드 두 장입니다.

1 /doctor — 자가 진단

/doctor

Claude Code가 스스로 환경을 점검합니다. Node.js 버전, 인증 상태, 설정 파일 등을 체크해서 문제가 있으면 알려줍니다. 병원 가기 전에 체온 재보는 것과 같습니다.

2 /bug — 버그 리포트

/bug

진짜 버그인 것 같다면 이 명령어로 Anthropic에 직접 보고할 수 있습니다. 현재 환경 정보가 자동으로 포함되어 전송됩니다.

에러별 대응 요약

에러 상황	첫 번째로 시도할 것	그래도 안 되면
command not found	터미널 새로 열기	npm 재설치
로그인 실패	인증 URL 직접 복사	/logout 후 재시도
응답 느림	/compact	/clear
지시 무시	구체적으로 다시 지시	CLAUDE.md에 규칙 작성
파일 잘못 수정	Esc 두 번 (되감기)	Shift+Tab (계획 모드)
기억 못함	/compact	새 대화 시작
한글 깨짐	UTF-8 설정	VS Code 터미널 사용

자주 묻는 질문 (FAQ)

Q. 에러 메시지가 영어로만 나오는데, 번역해도 되나요?

번역보다 에러 메시지를 그대로 Claude Code에 붙여넣는 게 더 빠릅니다. "이 에러가 뭔지 설명해줘"라고 물어보면 한글로 원인과 해결법을 알려줍니다. AI한테 에러를 물어보는 것도 AI를 잘 쓰는 방법입니다.

Q. Esc 두 번 눌렀는데 되돌아가지 않아요.

AI가 아직 작업 중일 때는 Esc가 "작업 중단" 역할을 합니다. 작업이 완전히 끝난 뒤에 Esc 두 번을 눌러야 되감기가 작동합니다. 타이밍이 중요합니다.

Q. /doctor를 실행했는데 문제가 없다고 나옵니다. 그런데 여전히 이상해요.

/doctor는 환경 설정 문제만 점검합니다. AI의 응답 품질 문제라면 대화가 길어진 것이 원인일 가능성이 높습니다. /compact나 새 대화를 먼저 시도해보세요.

정리하며

관점 한 스푼: 에러를 두려워하면 아무것도 시도하지 않게 됩니다. 코딩을 몰라도 에러는 해결할 수 있습니다. 사실 에러 메시지는 "여기가 문제야"라고 친절하게 알려주는 안내문입니다. 그걸 읽는 법을 배우면 더 이상 빨간 글씨가 무섭지 않습니다. AI 도구를 쓰면서 가장 빠르게 성장하는 순간은 에러를 만났을 때입니다. 에러를 만나고, 해결하고, 다시 시도하는 그 과정 자체가 실력입니다.

시리즈 전체 목차

클로드 코드 왕초보 가이드 — 전체 시리즈

#멜론 AI 인사이트 #Claude Code #초보자 가이드 #비개발자 #에러 해결

다음 편에서 비용 관리법을 알아봅니다

10편: 비용 관리, 얼마나 쓰고 있는지 확인하는 법 (곧 공개) →

참고 자료
· Anthropic 공식 문서 — Claude Code Documentation

멜론 AI 인사이트 Melon AI Insight