클로드 코드 오류 로그, 알고 보니 가장 정확한 힌트였어요 (실제 해결 5가지)

클로드 코드로 한창 작업하다가 터미널이 갑자기 영문 빨간 글씨로 뒤덮이면, 저는 한동안 그냥 창을 닫아버렸어요. 읽어도 모르겠고, 읽는 동안 뭔가 더 망가질 것 같았거든요.

그런데 몇 달 삽질하고 나서 알게 된 결론부터 말하면, 오류 로그는 나를 혼내는 경고가 아니라 원인이 이미 적혀 있는 답안지에 가까웠어요. 클로드 코드는 –debug 옵션으로 더 자세한 기록을 남길 수 있고, 그 기록의 마지막 40줄에서 첫 번째 Error 줄과 종료 코드만 확인해도 원인 대부분이 좁혀져요.

코딩을 따로 배운 적 없는 입장에서, 로그가 어디에 저장되는지 찾는 것부터 실제로 다섯 가지 오류를 하나씩 해결한 과정까지 그대로 적어볼게요. 중간에 헤맸던 부분도 숨기지 않고 남겨뒀어요.

• 오류 로그는 경고가 아니라 힌트예요
• 클로드 코드 오류 로그는 어디에 남을까
• –debug로 자세한 로그 켜고 파일로 저장하기
• 영문 로그, 이 3곳만 보면 원인이 좁혀져요
• 내 환경 문제인지 서버 장애인지 30초 만에 가르기
• 직접 겪은 오류 5가지와 해결 기록
• 오류 로그를 클로드에게 그대로 붙여넣는 방법
• 그래도 안 되면, 재현 절차 정리와 제보
• 자주 묻는 질문
• 참고자료

오류 로그는 경고가 아니라 힌트예요

처음 한 달 동안 저는 오류가 뜨면 바로 클로드에게 "아까 그거 안 돼요"라고만 말했어요. 로그는 스크롤 위로 지나가버렸고, 클로드는 추측으로 엉뚱한 파일을 고쳤죠. 같은 문제로 세 번을 반복하고 나서야, 내가 버린 그 영문 덩어리가 사실 가장 정확한 단서였다는 걸 알았어요.

영문 오류 로그는 대체로 세 부분으로 이루어져 있어요. 첫째는 EACCES나 ENOENT 같은 대문자 코드예요. 이건 오류의 종류를 나타내는 이름표라서, 이것만 검색해도 절반은 풀려요.

둘째는 그 옆에 붙은 사람이 읽는 문장이에요. permission denied, no such file or directory처럼 실제로 무엇이 막혔는지 알려줘요. 셋째는 그 아래 줄줄이 이어지는 파일 경로 목록, 즉 스택 트레이스예요. 어디서 멈췄는지를 알려주는 지도죠.

여기서 대부분이 겁을 먹는 이유는 셋째 부분이 제일 길고 제일 무서워 보이기 때문이에요. 그런데 실제로 원인이 적혀 있는 곳은 첫째와 둘째예요. 스택 트레이스는 원인을 확정할 때만 잠깐 보면 돼요. 이 순서만 바꿔도 체감 난이도가 확 내려가요.

그럼 여기서 바로 드는 질문. 로그가 화면에 뜨기도 전에 프로그램이 그냥 꺼져버리면 어떻게 하냐는 거예요. 그래서 로그가 "남는 곳"부터 확인해야 해요.

클로드 코드 오류 로그는 어디에 남을까

클로드 코드는 대화 기록과 설정을 사용자 홈 폴더의 .claude 폴더 아래에 모아둬요. 터미널에서 ls -al ~/.claude를 쳐보면 뭐가 들어 있는지 바로 보여요. 저는 이걸 처음 열어봤을 때 "아, 내 작업이 다 여기 있었구나" 싶어서 좀 안심했어요.

여기서 제일 중요한 사실 하나. 클로드 코드가 자동으로 남기는 세션 기록은 오류 원인 분석용 로그가 아니에요. 대화 내용이지 프로그램 내부 진단 기록이 아니거든요. 그래서 "로그 파일 위치만 찾으면 다 해결되겠지" 하고 접근하면 한 번 헛물을 켜요. 저도 .jsonl 파일을 열어놓고 30분을 뒤졌는데, 원하는 단서는 결국 터미널 쪽에 있었어요.

대신 세션 기록은 다른 데서 유용해요. claude --resume으로 이전 세션을 다시 열면, 오류가 나기 직전에 어떤 명령을 시켰는지 문맥을 통째로 되살릴 수 있어요. 재현 조건을 정리할 때 이게 결정적이에요.

–debug로 자세한 로그 켜고 파일로 저장하기

기본 화면에 보이는 오류는 요약본이에요. 진짜 단서는 디버그 모드를 켰을 때 나와요. 명령 하나 붙이는 게 전부인데, 저는 이걸 몰라서 며칠을 돌아갔어요.

영문 로그, 이 3곳만 보면 원인이 좁혀져요

로그를 얻었으면 이제 읽어야 하는데, 요령은 하나예요. 위에서부터 읽지 말고 아래에서 위로 올라가세요. 마지막 줄 근처가 실제로 멈춘 지점이고, 위쪽은 거기까지 오는 과정일 뿐이거든요.

실제로 제가 처음 만난 로그를 그대로 옮겨볼게요.

npm error code EACCES
npm error syscall mkdir
npm error path /usr/local/lib/node_modules/@anthropic-ai
npm error errno -13
npm error Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/@anthropic-ai'

여기서 봐야 할 건 딱 세 곳이에요. 첫째 EACCES는 권한 문제라는 이름표. 둘째 mkdir은 폴더를 만들려다 막혔다는 동작. 셋째 /usr/local/lib은 시스템 공용 폴더라는 위치예요.

이 세 개를 이으면 한 문장이 나와요. "시스템 공용 폴더에 새 폴더를 만들려다 권한이 없어서 막혔다." 여기까지 오면 검색어도 달라져요. "클로드 코드 설치 안 됨"이 아니라 "npm 전역 설치 권한 오류"로 검색하게 되고, 답이 훨씬 빨리 나와요.

자주 나오는 대문자 코드는 몇 개 안 돼요. 이 정도만 외워두면 웬만한 로그는 첫 줄에서 감이 와요.

종료 코드도 알아두면 편해요. 0은 정상이고, 1은 일반적인 오류예요. 126은 실행 권한 없음, 127은 명령 자체를 못 찾음, 130은 내가 Ctrl+C로 껐다는 뜻, 137은 메모리 부족 등으로 강제 종료된 경우예요. 특히 127이 뜨면 십중팔구 PATH 문제라서 설치가 아니라 경로부터 봐야 해요.

내 환경 문제인지 서버 장애인지 30초 만에 가르기

제가 가장 크게 시간을 날린 날은, 알고 보니 제 컴퓨터엔 아무 문제가 없던 날이었어요. 두 시간 동안 재설치를 세 번 했는데 그냥 서비스 쪽 일시 장애였거든요. 그 뒤로는 무조건 이 순서를 먼저 밟아요.

첫째, 상태 페이지를 열어요. 장애 표시가 떠 있으면 거기서 끝. 커피 마시고 기다리면 돼요. 둘째, 스마트폰 핫스팟으로 네트워크를 바꿔서 한 번만 다시 시도해봐요. 회사 와이파이나 학교망에서 막히는 경우가 생각보다 많아요. 이 두 가지에 30초면 충분해요.

셋째, 완전히 다른 빈 폴더를 만들어서 거기서 클로드 코드를 새로 실행해봐요. 거기선 멀쩡하다면 프로그램이 아니라 그 프로젝트의 설정 파일이 원인이에요. 범위가 단번에 좁혀지죠.

직접 겪은 오류 5가지와 해결 기록

지금까지 제 노트에 쌓인 것 중 반복해서 만난 다섯 가지예요. 표로 먼저 정리하고, 특히 헤맸던 두 개는 아래에 과정을 그대로 적어둘게요.

권한 오류(EACCES)부터요. 처음엔 앞에 sudo를 붙여서 넘겼어요. 설치는 됐는데 그 뒤로 업데이트할 때마다 같은 오류가 나고, 나중엔 파일 소유자가 꼬여서 더 골치였어요. 결국 전역 설치 위치를 홈 폴더 쪽으로 바꾸고 npm config set prefix ~/.npm-global 그 경로를 PATH에 추가한 다음 다시 설치하니 깔끔해졌어요. 관리자 권한으로 밀어붙이는 건 당장은 되지만 나중에 두 배로 돌아와요.

코드 1로 종료됨이 제일 억울했어요. 어제까지 멀쩡하던 게 아침에 안 켜지는데 메시지도 한 줄뿐이었거든요. –debug를 붙였더니 설정 파일을 읽다가 멈춘 게 보였고, 열어보니 전날 제가 항목을 추가하면서 마지막 줄에 쉼표를 하나 남겨뒀더라고요. JSON은 마지막 항목 뒤 쉼표를 허용하지 않아요.

그 뒤로는 설정을 손대면 바로 검사해요. node -e "JSON.parse(require('fs').readFileSync(process.argv[1],'utf8'))" ~/.claude/settings.json 를 돌려서 아무 말도 안 나오면 통과예요. 설정 파일이 멀쩡한데도 코드 1이면 훅이나 확장 기능을 잠깐 꺼보고 하나씩 되살리면서 범인을 찾아요.

MCP 서버 연결 실패는 접근법이 조금 달라요. 클로드 코드가 그 서버를 대신 실행해주는 구조라서, 같은 명령을 터미널에서 직접 쳐보면 진짜 오류가 그대로 나와요. 제 경우엔 실행 파일을 상대경로로 적어둔 게 문제였고, 절대경로로 바꾸니 바로 붙었어요. 시작이 오래 걸려서 끊기는 경우엔 대기 시간을 늘리는 설정을 함께 확인해보세요.

반복 로그아웃은 로그인 방식이 섞였을 때 자주 생겨요. 구독 계정으로 로그인해두고 터미널 환경변수에 별도 키가 남아 있으면 서로 밀어내요. env | grep -i anthropic 으로 남은 값이 있는지 확인하고, 필요 없으면 셸 설정에서 지운 뒤 다시 로그인하면 대체로 잡혀요.

오류 로그를 클로드에게 그대로 붙여넣는 방법

로그를 읽을 줄 알게 되면서 가장 크게 달라진 건, 클로드에게 던지는 질문의 질이었어요. "안 돼요"와 "이 로그가 나왔어요"는 답변 품질이 완전히 달라요.

요령은 세 가지예요. 첫째, 로그 전체가 아니라 마지막 40~60줄만 넣어요. 3천 줄을 통째로 넣으면 대화 길이만 잡아먹고 정확도는 오히려 떨어져요. 둘째, 곧바로 고치라고 하지 말고 원인 후보부터 물어봐요. 셋째, 내 환경 정보를 같이 줘요.

아래 오류를 해결하려고 해. 바로 코드를 고치지 말고 순서대로 답해줘.
1) 하려던 작업 — 2) 실행한 명령 — 3) 환경 — macOS 15, node -v 결과, claude --version 결과 4) 이미 시도한 것 — 5) 오류 로그(마지막 50줄) —
원인 후보를 가능성 높은 순으로 3개 뽑고, 각각 어떤 명령으로 확인하는지 알려줘. 확인이 끝나면 그때 수정안을 제안해줘.

이렇게 물으면 클로드가 추측으로 파일을 건드리는 대신 확인 명령을 먼저 제시해요. 저는 이 템플릿을 쓰고 나서 한 번에 해결되는 비율이 눈에 띄게 올라갔어요. 특히 4번 항목이 중요해요. 이미 해본 걸 적어주지 않으면 똑같은 방법을 다시 제안받거든요.

그래도 안 되면, 재현 절차 정리와 제보

여기까지 왔는데도 안 풀린다면, 이제부터 할 일은 "더 시도하는 것"이 아니라 "정리하는 것"이에요. 정보를 갖춰서 물어보면 커뮤니티든 이슈 트래커든 답이 훨씬 빨리 와요.

세션 안에서 /bug 명령을 쓰면 이 정보를 모아 제보하는 흐름으로 이어져요. 이슈 트래커에서 같은 문구로 먼저 검색해보는 것도 좋아요. 저는 검색 한 번으로 이미 올라온 해결책을 찾은 적이 두 번 있었어요.

마지막 수단으로는 되돌리기가 있어요. 업데이트 직후부터 문제가 생겼다면 이전 버전을 지정해서 설치해두고 며칠 기다리는 것도 방법이에요. 다만 클로드 코드는 설치 방식이 여러 가지라, 내가 어떤 방식으로 깔았는지에 맞는 절차를 공식 문서에서 확인한 뒤 진행하는 게 안전해요. 명령을 그대로 복사하기 전에 한 번 읽어보는 습관이 결국 시간을 아껴줘요.

자주 묻는 질문

클로드 코드 오류 로그는 어디에 저장되나요

기본 오류 출력은 터미널 화면에만 남고 창을 닫으면 사라져요. 남기려면 claude --debug 2>&1 | tee ~/Desktop/claude-debug.log 처럼 직접 파일로 저장해야 해요. 대화 세션 기록은 홈 폴더의 .claude 안 projects 폴더에 저장되지만, 이건 진단 로그가 아니라 대화 내용이에요.

디버그 모드는 어떻게 켜나요

실행 명령 뒤에 –debug를 붙이면 돼요. 확장 서버 연결 과정까지 함께 찍혀서 원인 찾기가 훨씬 쉬워져요. 세션 안에서는 /doctor로 설치 상태를, /status로 로그인과 버전을 확인할 수 있어요.

프로세스가 코드 1로 종료됨은 무슨 뜻인가요

일반적인 실패라는 뜻이라 그 자체로는 원인을 알려주지 않아요. 실제로는 설정 파일 문법 오류, 훅 스크립트 실패, 실행 환경 버전 문제가 흔한 원인이에요. –debug로 다시 실행해서 멈춘 지점을 먼저 확인하고, settings.json에 마지막 쉼표가 남아 있지 않은지 검사해보세요.

계속 로그아웃되는 이유는 뭔가요

로그인 방식이 겹쳤을 가능성이 커요. 구독 계정 로그인과 별도 키가 환경변수에 함께 남아 있으면 서로 밀어내요. 남은 환경변수를 확인해서 정리한 뒤 다시 로그인해보세요. 그래도 반복되면 인증 정보를 초기화하고 새로 로그인하는 흐름을 공식 문서에서 확인하는 게 좋아요.

서버 장애인지 내 환경 문제인지 어떻게 구분하나요

상태 페이지를 먼저 열어보는 게 가장 빨라요. 로그에 500번대 응답이나 과부하 표시가 있으면 서비스 쪽 문제라 내 컴퓨터를 뒤질 필요가 없고, 401이나 403이면 내 로그인 쪽, 429면 사용 한도 쪽이에요.

참고자료

• Claude Code 공식 문제 해결 문서 — 설치·인증·권한 오류의 공식 대응 절차
• Anthropic 서비스 상태 페이지 — 장애 여부를 가장 먼저 확인하는 곳
• Claude Code 이슈 트래커 — 같은 오류 문구로 검색하고 제보하는 공간
• Node.js 공식 사이트 — 실행 환경 버전과 설치 방법 확인

저는 여전히 오류를 자주 만나요. 다만 지금은 빨간 글씨가 뜨면 창을 닫는 대신 –debug를 붙이고 마지막 50줄을 저장해요. 대문자 코드 하나, 동작 하나, 경로 하나를 이어서 한 문장으로 만들어보면 대체로 다음에 뭘 해야 할지가 보이더라고요.

오류 로그를 읽을 줄 알게 된 게 코딩을 배운 것보다 더 큰 변화였어요. 막혔을 때 남에게 물어볼 말이 생기고, 클로드에게도 훨씬 정확하게 도움을 요청할 수 있게 되니까요. 오늘 터미널에 떠 있는 그 메시지도 나를 막는 벽이 아니라, 이미 답을 절반쯤 적어둔 쪽지예요.

다음엔 제가 실제로 쌓아온 오류 노트를 정리하는 방법도 기록해볼게요. 같은 데서 두 번 멈추지 않는 게 결국 제일 빠른 길이더라고요.

함께 보면 좋은 글

• 워드프레스 플러그인 설치와 오류 해결 순서
• 커서 vs 클로드 코드 비교, 비전공자가 뭘 골라야 할까
• 워드프레스 이미지 업로드 오류, 비전공자가 직접 고친 해결법 7가지