command not found 또는 TLS 오류와 같은 설치 오류는 설치 및 로그인 문제 해결을 참조하십시오.
Claude Code 자체가 아닌 실행 프로그램이 출력하는 래퍼 및 IDE 오류를 제외하면, 이러한 오류와 복구 명령은 CLI, 데스크톱 앱, 클라우드 세션에 모두 적용됩니다. 세 가지 모두 동일한 Claude Code CLI를 래핑하기 때문입니다. 기타 사용 환경별 문제는 해당 사용 환경 페이지의 문제 해결 섹션을 참조하십시오.
Claude Code는 모델 응답을 위해 Claude API를 호출하므로 대부분의 런타임 오류는 기본 API 오류 코드에 매핑됩니다. 이 페이지에서는 Claude Code 내에서 각 오류의 의미와 복구 방법을 다룹니다. 원본 HTTP 상태 코드 정의는 Claude Platform 오류 참조를 참조하십시오.
오류 찾기
표시되는 메시지와 일치하는 아래 섹션을 찾으세요.자동 재시도
Claude Code는 일시적인 실패가 발생하면 오류를 표시하기 전에 지수 백오프를 적용하여 최대 10회까지 재시도합니다. 다만 Claude의 응답 도중에 발생한 실패를 항상 재시도하는 것은 아닙니다. 이 페이지의 오류 중 하나가 표시되었다면, Claude Code는 해당 실패에 적용되는 재시도를 이미 모두 수행한 것입니다. Claude Code는 다음 실패를 재시도합니다.- Claude의 응답이 스트리밍되기 전에 발생한 서버 오류, 과부하 응답, 요청 시간 초과.
- Claude가 사고를 마친 후 텍스트나 도구 호출을 시작하기 전에 발생한 서버 오류 또는 과부하 응답. 이 시점의 서버 오류는 최대 2회까지 재시도합니다. v2.1.284 이전에는 이 시점에서 Claude Code가 오류와 함께 턴을 종료했습니다.
- 끊어진 연결. Claude가 사고를 포함하여 응답의 어떤 부분도 완료하기 전에 요청 도중 연결이 끊어지면, 일부 텍스트가 이미 스트리밍되기 시작했더라도 Claude Code는 동일한 백오프로 요청을 다시 보내고 턴이 계속됩니다. Claude가 사고를 마친 후 텍스트나 도구 호출을 시작하기 전에 연결이 끊어지면, Claude Code는 대신 요청을 빠르게 연달아 최대 2회 다시 보내며, 이 시점에서 연결이 계속 끊어지면
Connection lost before a response was produced와 함께 턴을 종료합니다. - 요청 도중 컴퓨터가 절전 모드로 전환되어 연결이 끊어졌다고 Claude Code가 감지한 경우. Claude Code는 이를 위 규칙에 따른 끊어진 연결로 간주합니다. 재시도 레이블에 구체적인 이유가 표시되면
Connection lost while your computer was asleep로 표시되며, Claude가 사고를 마친 후 텍스트나 도구 호출 전에 턴이 종료되면 메시지는Your computer went to sleep before a response was produced로 표시됩니다. - 응답 헤더는 도착했지만 Claude의 응답이 전혀 도착하지 않았거나, Claude가 사고를 마쳤지만 텍스트나 도구 호출을 시작하지 않은 상태에서 멈춘 응답 스트림: Claude Code는 멈춘 연결을 중단하고 요청을 최대 1회 다시 스트리밍합니다. Claude가 사고를 마친 후 텍스트나 도구 호출 전에 응답이 두 번째로 멈추면, Claude Code는
The response stalled before a response was produced와 함께 턴을 종료합니다. - 첫 바이트 기한이 적용되는 연결에서 API가 응답 헤더로 전혀 응답하지 않는 스트리밍 요청. 기한에 도달하면 Claude Code는 요청을 중단하고 재시도 예산 내에서 다시 보냅니다. 다시 보낸 요청에서도 기한이 만료되면 No response from API와 함께 턴이 종료됩니다.
CLAUDE_CODE_RETRY_WATCHDOG을 설정하면 Claude Code는 대신 예산 내에서 계속 다시 보냅니다. - Claude가 사고를 마치거나 텍스트 또는 도구 호출을 시작하기 전에 API의 출력 콘텐츠 필터가 중단시킨 스트리밍 응답. Claude Code는 재시도 예산 내에서 요청을 1회 다시 보내며, 필터가 두 번째 응답도 중단시키면 Output blocked by content filtering policy를 표시합니다.
- 일시적인 429 스로틀. 단, 게이트웨이의 지출 한도
429는 스로틀이 아니므로 제외됩니다. Spend limit reached를 참조하세요.- claude.ai 구독으로 로그인한 경우, 플랜의 할당량 헤더가 포함되지 않은 429 스로틀도 여기에 포함됩니다. v2.1.199 이전에는 Claude Code가 API 키 및 Enterprise 로그인에 대해서만 이러한 스로틀을 재시도했습니다.
- 입력과
max_tokens의 합이 컨텍스트 한도를 초과하여 거부된 요청. 변경 없이 다시 보내면 같은 방식으로 실패하므로, Claude Code는max_tokens를 줄여서 재시도하며, 다음 두 경우에는 재시도를 중단하고 대신 압축을 수행합니다.- 어떤 감소로도 맞출 수 없는 경우. 예를 들어 대화 자체가 컨텍스트 윈도우를 거의 채운 경우입니다.
- 재시도에서
max_tokens를 더 이상 줄일 수 없는 경우. v2.1.218 이전에는 확장 사고 예산이 남은 컨텍스트를 초과하는 경우처럼, 여전히 맞지 않는 축소된 요청을 재시도 예산이 소진될 때까지 다시 보낼 수 있었습니다.
- Claude가 도구를 호출한다고 나타내지만 도구 호출이 포함되지 않은 응답. Claude Code는 Claude에게 도구 호출을 요청하는 방식으로 최대 2회 재시도합니다. 두 재시도가 모두 같은 방식으로 실패하면
The model's tool call could not be parsed (retry also failed).가 표시되고 턴이 종료됩니다. 다시 시도하려면 다른 메시지를 보내세요. v2.1.307 이전에는 Claude Code가 턴을 종료하기 전에 1회 재시도했습니다. - Google Cloud의 Agent Platform에서 만료되었거나 누락된 Google Cloud 자격 증명, 또는 사용자의 컴퓨터에서 로드에 실패한 AWS 자격 증명. Claude Code는 캐시된 자격 증명을 폐기하고 최대 2회 재시도한 다음, Could not load AWS or Google Cloud credentials에 설명된 대로 즉시 다시 인증할 수 있도록 오류를 보고합니다. v2.1.228 이전에는 실패한 Google Cloud 자격 증명을 전체 재시도 예산만큼 재시도한 후에 오류를 표시했습니다.
apiKeyHelper스크립트가 자격 증명을 제공하는 동안 Anthropic API에서 직접 또는 LLM 게이트웨이를 통해 받은401또는403. Claude Code는 스크립트를 다시 실행하고 새 출력으로 전체 재시도 예산 내에서 재시도합니다. 다시 실행할 때 스크립트 자체가 실패하면, Claude Code는 대신 Your apiKeyHelper script is failing을 표시합니다.
Connection lost before a response was produced가 Connection closed while thinking, before producing a response로, The response stalled before a response was produced가 Response stalled while thinking, before producing a response로 표시되었습니다.
Claude Code는 다음 실패를 재시도하지 않습니다.
- TLS 검사 프록시, 누락된
NODE_EXTRA_CA_CERTS번들, 만료된 인증서 등으로 인한 TLS 인증서 검증 실패. Claude Code는 첫 번째 시도에서 오류를 보고하므로 인증서 설정을 즉시 수정할 수 있습니다. SSL 인증서 오류를 참조하세요. 핸드셰이크 시간 초과와 같은 일시적인 TLS 상황은 여전히 재시도합니다. v2.1.199 이전에는 인증서 실패를 전체 재시도 예산만큼 재시도한 후에 오류를 표시했습니다. - Claude가 텍스트 블록이나 도구 호출을 완료한 후, 또는 사고를 마친 후 이를 시작한 후, 응답을 마치기 전에 발생한 서버 오류, 끊어진 연결 또는 멈춘 스트림. 같은 도구 호출이 두 번 실행될 수 있으므로 Claude Code는 요청을 다시 실행하지 않습니다. 대신 Claude가 완료한 내용을 유지하고, Claude가 완료한 도구 호출을 실행한 다음, 그 결과에서 턴을 계속합니다. 대화형 세션과 비대화형 세션에서 표시되는 내용은 The response above may be incomplete를 참조하세요. v2.1.199 이전에는 스트림 도중 서버 오류가 발생하면 부분 출력을 폐기하고 전체 턴을 오류로 보고했습니다.
- Claude가 응답을 마친 후 발생한 실패: 재시도할 것이 없으므로 Claude Code는 완성된 응답을 유지하고 턴을 정상적으로 종료합니다.
- 예상치 못한 content-type을 가진 Amazon Bedrock 스트리밍 응답. 응답을 재작성하는 게이트웨이나 프록시가 재시도도 같은 방식으로 재작성하기 때문입니다. Claude Code v2.1.208 이상이 필요합니다.
- 실패한 스트리밍 요청의 비스트리밍 재시도가 성공 상태를 받았지만 본문에 Claude API 메시지가 없는 경우. Claude Code는 해당 오류와 함께 턴을 종료합니다.
- 조직의 정책 검사에서 거부된 요청. 이는 거부 메시지가 포함된
API Error:줄로 표시됩니다. 조직의 관리자는 Claude Enterprise 기능인 Inference hooks로 검사를 설정하며, 메시지는 관리자가 구성한 안내로 끝나거나 기본적으로 관리자에게 문의하라고 안내합니다. 거부는 모델이 아니라 요청의 내용에 관한 것이므로, Claude Code는 거부된 요청을 같은 모델이나 대체 모델로 다시 보내지 않습니다. v2.1.239 이전에는 거부 내용을 표시하기 전에 거부된 요청을 스트리밍 없이 또는 구성된 대체 모델로 다시 보낼 수 있었습니다.
Claude Code가 재시도하거나 대기하는 동안 표시되는 내용
재시도하는 동안 스피너는 오류 레이블 뒤에Retrying in Ns · attempt x/y 카운트다운을 표시합니다. 네트워크 중단, TLS 핸드셰이크 실패, 속도 제한 도달처럼 즉시 조치할 수 있는 실패의 경우 레이블은 첫 번째 시도부터 구체적인 이유를 표시합니다. 그 밖의 오류는 처음에 API error로 표시됩니다. v2.1.198부터는 세 번째 시도부터, 또는 CLAUDE_CODE_MAX_RETRIES가 3회 미만을 허용하는 경우 마지막 시도에서 구체적인 이유로 전환됩니다. 이전 버전에서는 마지막 시도에서만 전환됩니다.
v2.1.198부터는 재시도 중에 일반적인 스피너 팁이 표시되지 않습니다. 오류 이유가 표시된 후 실패가 529 과부하인 경우, 카운트다운 아래 줄에 서비스 상태를 확인할 위치도 표시됩니다. Anthropic API에서는 status.claude.com, 다른 구성에서는 메시지에 명시된 공급자 또는 게이트웨이 호스트입니다.
Waiting for API response
Waiting for API response · will retry in … · check your network 배너는 Claude Code가 요청에 대한 데이터를 전혀 받지 못한 채 최소 20초 동안 기다렸음을 의미합니다. 요청이 아직 실패한 것은 아닙니다. 카운트다운은 Claude Code가 멈춘 연결을 중단하는 시점까지 진행됩니다. 중단이 발생하는 시점에 따라 다음과 같이 처리됩니다.
- Claude가 텍스트 블록이나 도구 호출을 완료하기 전, 또는 사고를 마친 후 이를 시작하기 전이라면, Claude Code는 요청을 재시도하거나 오류와 함께 턴을 종료합니다. 어떤 멈춤을 몇 번 재시도하는지는 자동 재시도에 설명되어 있습니다.
- Claude가 텍스트 블록이나 도구 호출을 완료한 후, 또는 사고를 마친 후 이를 시작한 후, Claude가 응답을 마치기 전이라면, Claude Code는 Claude가 완료한 내용을 유지하고 Claude가 완료한 도구 호출에서 턴을 계속하며 The response above may be incomplete를 표시합니다. 비대화형 세션에서, 그리고 모든 세션의 서브에이전트 응답에 대해서는 Claude Code가 먼저 Claude에게 응답을 계속하도록 요청할 수 있습니다. 언제 그렇게 하는지와 언제 여전히 해당 알림이 표시되는지는 해당 항목에 설명되어 있습니다.
- Claude가 응답을 마친 후라면, Claude Code는 턴을 정상적으로 종료합니다.
게이트웨이 뒤에서 대기 배너가 나타났다 사라지는 경우
게이트웨이를 통해 연결한 상태에서 Claude가 사고하는 동안Waiting for API response 배너가 나타났다 사라지기를 반복한다면, Claude Code를 업데이트하여 v2.1.309 이상을 사용하세요. 다음 연결에서는 데이터 없이 45초가 지나야 배너가 표시됩니다.
ANTHROPIC_BASE_URL이 LLM 게이트웨이처럼 Anthropic API가 아닌 호스트로 설정된 경우- Claude apps gateway 세션
ANTHROPIC_AWS_BASE_URL이 설정된 Claude Platform on AWS
재시도 동작 조정
다음 환경 변수로 재시도 동작을 조정할 수 있습니다.비스트리밍 시도의 대기 시간
비스트리밍 시도는 요청 타임아웃과 본문 유휴 타임아웃 중 먼저 도달하는 시점에 종료됩니다.- 요청 타임아웃: 양수 값을 설정한 경우
API_TIMEOUT_MS, 그렇지 않으면 로컬 세션에서 300초입니다. - 본문 유휴 타임아웃: 이 타임아웃이 적용되고 사용자가 끄지 않은 경우,
API_TIMEOUT_MS를 아무리 높게 설정하더라도 응답 없이 5~6분이 지나면 종료됩니다.
서버 오류
이러한 오류의 대부분은 추론 제공자에서 발생합니다: Anthropic API의 Anthropic 서비스, Amazon Bedrock의 해당 제공자 엔드포인트 뒤의 서비스, Google Cloud의 Agent Platform, Microsoft Foundry 또는 사용자 정의 게이트웨이입니다. 자동 모드가 작업의 안전성을 결정할 수 없음 및 API 오류로 인해 에이전트가 조기에 종료됨은 또한 사용자 측의 원인을 다룹니다. 예를 들어 분류기 모델을 호출할 수 없는 Amazon Bedrock 계정이나 사용 한도에 도달한 서브에이전트입니다.API 오류: 500 내부 서버 오류
Claude Code는 모든 5xx 응답에 대해 상태 코드와 API의 오류 메시지를 표시합니다. 아래 예제는 Anthropic API의 500 응답을 보여줍니다:ANTHROPIC_BASE_URL은 게이트웨이 호스트를 명시합니다.
API 자체의 5xx는 API 내부의 예상치 못한 실패를 나타냅니다. 이는 사용자의 프롬프트, 설정 또는 계정으로 인해 발생하지 않습니다.
프록시, 로드 밸런서 또는 게이트웨이가 HTML 오류 페이지로 응답할 때 메시지는 상태 코드와 페이지의 제목(예: API Error: 502 Bad Gateway)을 표시합니다. 제목이 없는 페이지의 경우 메시지는 상태 코드와 표준 이름을 대신 표시합니다. v2.1.281 이전에는 페이지에 제목이 있을 때 상태 코드가 삭제되었고 제목이 없을 때 페이지의 원본 마크업이 인쇄되었습니다.
수행할 작업:
- status.claude.com 또는 메시지에 명시된 제공자 상태 페이지에서 활성 인시던트를 확인합니다
- 1분 기다린 후 메시지를 다시 보냅니다. 원본 메시지는 여전히 대화에 있으므로 긴 프롬프트의 경우 전체를 다시 붙여넣는 대신
try again을 입력할 수 있습니다. ANTHROPIC_BASE_URL이 LLM 게이트웨이를 가리키고 모든 요청이 이런 방식으로 실패하면 게이트웨이와 그 업스트림이 도구 검색 필드를 허용하는지 확인합니다. 기본적으로 Claude Code는defer_loading도구 필드와tool_reference블록을 이를 활성화하는anthropic-beta헤더와 함께 보냅니다. v2.1.304 이전에는ENABLE_TOOL_SEARCH로 켜지 않는 한 게이트웨이 뒤에서 도구 검색이 꺼져 있었습니다.- 오류가 게시된 인시던트 없이 계속되면
/feedback을 실행하여 Anthropic이 요청 세부 정보로 조사할 수 있도록 합니다. 환경에서/feedback을 사용할 수 없는 경우 오류 보고를 참조하세요.
API 오류: 반복된 529 오버로드 오류
API가 모든 사용자에게 일시적으로 용량이 부족합니다. Claude Code는 이 메시지를 표시하기 전에 이미 여러 번 재시도했습니다:- status.claude.com 또는 메시지에 명시된 제공자 상태 페이지에서 용량 공지를 확인합니다
- 몇 분 후에 다시 시도합니다
-
/model을 실행하고 다른 모델로 전환하여 계속 작업합니다. 용량은 모델별로 추적되기 때문입니다. Claude Code는 한 모델이 특히 높은 부하를 받을 때 모델 전환을 요청합니다. 예를 들어Opus is experiencing high load, please use /model to switch to Sonnet입니다. Fable 모델에서 메시지는 Fable을 명시합니다. Claude Desktop 앱이 실행하는 세션(예: Code 탭 또는 Cowork)에서 메시지는Opus is experiencing high load. Switch to Sonnet.으로 읽히며 앱의 모델 선택기로 모델을 전환합니다.
요청 시간 초과
API가 연결 마감 시간 전에 응답하지 않았습니다.API_TIMEOUT_MS를 0으로 설정하면 이 요청 타임아웃이 꺼집니다. 첫 바이트 마감 시간과 본문 유휴 타임아웃은 0으로 설정해도 꺼지지 않으므로, 스트리밍 요청은 여전히 연결에 적용되는 타임아웃에 따라 실행됩니다. 비스트리밍 시도는 로컬 세션에서 300초 제한을 유지하므로 여전히 이 메시지로 끝날 수 있습니다.
수행할 작업:
- 모든 요청이 이 메시지로 실패하고
API_TIMEOUT_MS를0으로 설정한 경우claude --version을 확인합니다. v2.1.305 이전 버전이면 Claude Code를 업데이트하거나 양수 값을 설정합니다. - 요청을 다시 시도합니다
- 느린 네트워크 또는 프록시가 원인인 경우 자동 재시도에 설명된 대로
API_TIMEOUT_MS를 높입니다 - 시간 초과가 빈번하고 네트워크가 정상인 경우 아래의 네트워크 및 연결 오류를 참조하세요
API에서 응답 없음
Claude Code가 스트리밍 요청을 보냈고, API가 첫 바이트의 마감 시간 내에 응답 헤더를 반환하지 않았습니다. Claude Code는 이러한 요청을 전체API_TIMEOUT_MS 요청 타임아웃까지 기다리지 않고 중단하며, 재시도 예산이 허용하는 경우 요청을 다시 보냅니다. 재시도에서도 마감 시간이 지나면 턴이 이 메시지로 끝나며, 각 시도가 대기한 시간을 표시합니다.
CLAUDE_CODE_RETRY_WATCHDOG을 설정하면 Claude Code는 턴을 종료하는 대신 재시도 동작 조정에 설명된 예산 내에서 계속 재시도합니다.
-
첫 시도: 1 이상으로 설정할 때
CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS, 10초에서 30분 사이로 제한됩니다. 그렇지 않으면 Claude Code는 스트리밍 유휴 감시자에 나열된 바이트 수준 감시자 타임아웃을 사용하므로 해당 타임아웃을 변경하는 변수가 이 대기도 변경합니다. 어느 쪽이든 Claude Code는 요청 본문의 32KB마다 1초를 추가합니다. -
재시도:
API_TIMEOUT_MS보다 1초 적게, 기본값으로 거의 10분이므로 재시도가 응답을 생성이 완료될 때까지 보유하는 프록시 또는 게이트웨이를 초과할 수 있습니다. Amazon Bedrock에서 재시도는 첫 시도와 동일한 마감 시간을 사용하며 메시지는 두 가지 대신 하나의 기간을 표시합니다. Amazon Bedrock을 제외하고,API_TIMEOUT_MS를0으로 설정하면 재시도는 10분에 32KB당 1초를 더한 시간 동안 대기하며, 첫 시도의 대기가 더 길면 첫 시도만큼 대기합니다.
API_TIMEOUT_MS보다 1초 적은 값을 초과하지 않으며, 11초 미만의 양수 API_TIMEOUT_MS는 마감 시간을 끕니다. 바이트 수준 감시자는 응답 헤더가 도착한 후에만 시작되므로 그 후 바이트 전송을 중지하는 응답은 이 마감 시간 대신 정지된 스트림 규칙을 따릅니다.
Claude apps gateway 세션에서는 CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS를 1 이상으로 설정하여 이 마감 시간을 켠 경우에만 이 마감 시간이 적용됩니다.
수행할 작업:
- 메시지를 다시 보냅니다. 원본 메시지는 여전히 대화에 있으므로 긴 프롬프트의 경우 전체를 다시 붙여넣는 대신
try again을 입력할 수 있습니다. - 반복되면 네트워크 또는 프록시 문제로 취급합니다.
- 네트워크의 프록시 또는 게이트웨이가 응답을 생성이 완료될 때까지 보유하는 경우
API_TIMEOUT_MS를 높여 재시도가 더 오래 대기하도록 합니다. Amazon Bedrock에서CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS도 높입니다. - 첫 시도가 계속 시간 초과되고 재시도가 성공하면
CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS를 높여 첫 시도도 충분히 오래 대기하도록 합니다.
API_TIMEOUT_MS 요청 타임아웃(기본값 10분)을 기다렸습니다. v2.1.261 이전에는 재시도가 첫 시도와 동일한 마감 시간을 기다렸고 메시지는 기간을 표시하지 않았습니다. v2.1.307 이전에는 Claude Code가 Claude apps gateway 세션에서 CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS를 무시했습니다.
위의 응답이 불완전할 수 있음
스트리밍 요청이 응답이 진행 중일 때 실패했습니다. Claude가 텍스트 블록 또는 도구 호출을 완료한 후 또는 사고를 마친 후 하나를 시작했습니다. 요청을 다시 보내면 동일한 도구 호출을 두 번 실행할 수 있으므로 Claude Code는 Claude가 완료한 출력을 유지하고 턴을 버리는 대신 이 공지를 추가합니다. 표시되는 변형은 원인을 명시합니다:Server error mid-response: 스트림 중간 오버로드 또는 5xx 서버 오류입니다. 이 변형은 Claude Code v2.1.199 이상이 필요합니다. 그 이전에는 부분 출력을 버리고 전체 턴을 오류로 보고했습니다.Connection lost mid-response: 연결이 끊어졌습니다. 프록시 또는 게이트웨이가 응답이 완료되기 전에 응답 본문을 깔끔하게 종료할 때도 이 변형이 표시됩니다.Your computer went to sleep mid-response: Claude Code가 응답이 스트리밍되는 동안 컴퓨터가 절전 모드로 전환되었음을 감지했습니다. 컴퓨터가 깨어나면 Claude Code는 연결을 끊어진 것으로 취급하고 읽기를 중지합니다.Part of the response never arrived: 스트림 이벤트가 API와 Claude Code 사이에서 손실되어 나중 이벤트가 도착하지 않은 콘텐츠를 참조했습니다. v2.1.281 이전에는 이 경우 턴이API Error: Content block not found로 종료되었습니다.The response stream was malformed: 이미 완료된 콘텐츠 블록에 대한 이벤트가 도착했거나 손상된 이벤트가 도착했습니다. 손상된 이벤트는 데이터가 유효한 JSON이 아니거나 콘텐츠가 누락되었거나 콘텐츠가 이벤트의 유형과 일치하지 않는 이벤트입니다. v2.1.284 이전에는 파서의 원본 오류(예:API Error: JSON Parse error로 시작하는 오류)가 Claude가 사고, 텍스트 블록 또는 도구 호출을 완료한 후 유효하지 않은 JSON이 있는 이벤트가 도착했을 때 대신 나타났습니다.The response stopped arriving: 연결은 열려 있었지만 데이터 전달을 중지했으므로 스트리밍 유휴 감시자가 중단했습니다. v2.1.222 이전에는 Claude Code가ANTHROPIC_BASE_URL또는ANTHROPIC_AWS_BASE_URL을 통해 도달한 게이트웨이 연결에서 서버의 킵얼라이브 핑이 여전히 도착하는 동안 이 실패를 보고할 수 있었습니다. 파싱된 응답 이벤트만 계산했기 때문입니다. 업그레이드하면 해당 경로에서 이러한 거짓 시간 초과를 중지합니다.ANTHROPIC_BEDROCK_BASE_URL과 같은 제공자 기본 URL을 통해 도달한 게이트웨이는 바이트 감시자로 래핑되지 않습니다. 스트리밍 유휴 감시자를 참조하세요.
Connection lost mid-response가 Connection closed mid-response로 읽혔고 The response stopped arriving이 Response stalled mid-stream으로 읽혔습니다.
Claude가 텍스트 또는 도구 호출을 시작하기 전에 손실되거나 중복되거나 손상된 스트림 이벤트가 도착하면 이 공지가 표시되지 않습니다:
- Claude가 사고만 완료했으면 Claude Code가 요청을 다시 발급합니다. 다시 발급된 스트림이 동일한 방식으로 끊어지면 턴이
Part of the response never arrived and no response was produced. Try again.또는The response stream was malformed and no response was produced. Try again.으로 끝납니다. - 아무것도 완료되지 않았으면 Claude Code가 스트리밍 없이 요청을 다시 보냅니다.
CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK으로 해당 폴백을 끈 경우 턴이 손실된 이벤트에 대해API Error: Content block not found로 끝나거나 중복된 이벤트에 대해API Error: Content block already closed로 끝납니다. 손상된 이벤트의 경우 폴백이 꺼져 있으면 턴이API Error: Stream event unreadable또는 파서의 원본 오류로 끝납니다.
- 응답의 앞부분에서 Claude Code는 실패를 재시도하거나 다른 오류로 턴을 종료합니다. 자동 재시도를 참조하세요.
- 이러한 실패 중 하나가 Claude가 응답을 마친 후에 도착하면 Claude Code는 완전한 응답을 유지하고 이 공지 없이 턴을 정상적으로 종료합니다. v2.1.222 이전에는 Claude Code가 응답이 완료된 후 연결이 끊어지거나 정지되었을 때 이 공지를 표시했고 응답이 완전했음에도 불구하고 턴을 오류로 보고했습니다.
- 비대화형 세션(예:
-p실행, Agent SDK 실행 또는 클라우드 세션)에서 잘린 응답이 주 대화에 있고 텍스트를 포함하지만 도구 호출이 없는 경우continue를 직접 보낼 필요가 없습니다: Claude Code는 부분 출력을 유지하고 Claude에게 중단된 위치에서 계속하도록 요청하며, 최대 3번 연속으로 요청합니다. 이 공지는 Claude Code가 해당 연속을 모두 사용한 후에만 이러한 응답에 대해 표시됩니다. v2.1.246 이전에는 Claude Code가 비대화형 턴을 첫 번째 잘림에서 이 공지로 종료했습니다. - 서브에이전트에서, 세션이 대화형인지 여부와 관계없이: 잘린 응답이 텍스트를 포함하지만 도구 호출이 없을 때 Claude Code는 서브에이전트에게 계속하도록 요청합니다. 공지는 해당 연속을 모두 사용한 후에만 서브에이전트의 마지막 메시지가 됩니다. v2.1.257 이전에는 서브에이전트가 첫 번째 잘림에서 이 공지를 표시했습니다.
- 대화형 세션에서 화면에 남아 있는 응답을 읽습니다: Claude Code는 오류 전에 Claude가 완료한 모든 블록을 유지하지만 턴이 끝날 때 중단된 최종 블록을 버립니다. 따라서 최종 문장 또는 도구 호출이 누락될 수 있습니다.
continue로 회신하여 Claude가 마지막으로 완료한 블록에서 계속하도록 합니다. - 비대화형 모드(
-p):- 기본 텍스트 출력을 사용하면 Claude Code는 턴의 앞부분에서 여전히 보유한 마지막 완료된 텍스트 블록을 인쇄한 후 이 메시지를 인쇄합니다. 보유하지 않으면 Claude Code는 이 메시지만 인쇄합니다. 예를 들어 Claude Code가 턴 중간에 대화를 압축하고 해당 텍스트를 지웠기 때문입니다. v2.1.219 이전에는 Claude Code가
-p텍스트 출력에서 이 메시지만 인쇄했고 이미 생성한 응답을 버렸습니다. --output-format json또는stream-json을 사용하면 Claude Code는 이 메시지를result필드에 보고합니다.- 연결이 안정되면 턴을 계속하려면 세션을 재개하고 대화 계속에 설명된 대로
continue를 보냅니다.
- 기본 텍스트 출력을 사용하면 Claude Code는 턴의 앞부분에서 여전히 보유한 마지막 완료된 텍스트 블록을 인쇄한 후 이 메시지를 인쇄합니다. 보유하지 않으면 Claude Code는 이 메시지만 인쇄합니다. 예를 들어 Claude Code가 턴 중간에 대화를 압축하고 해당 텍스트를 지웠기 때문입니다. v2.1.219 이전에는 Claude Code가
자동 모드가 작업의 안전성을 결정할 수 없음
자동 모드가 작업을 분류하는 데 사용하는 모델이 결정을 내릴 수 없어 자동 모드가 작업을 자동으로 승인하지 않았습니다. 표시되는 메시지는 분류기가 실패한 방식에 따라 다릅니다. 분류기 모델을 사용할 수 없을 때:Not run · auto mode's check had no usable answer 행이 나타납니다. 이 행은 서버가 판정을 제공하지 않았다는 메시지나, 원격 세션이 아닌 경우 Auto mode could not evaluate로 시작하는 메시지를 대신할 수도 있습니다. Ctrl+O를 눌러 트랜스크립트 뷰어에서 해당 메시지를 확인합니다. v2.1.296 이전에는 메시지가 빨간색 오류로 나타났습니다.
Claude Code가 실패 범주를 결정할 수 있을 때 temporarily unavailable 뒤의 괄호에 범주를 명시합니다. 예를 들어 <model> is temporarily unavailable (rate-limited), so auto mode cannot determine the safety of <tool> right now입니다. 범주는 (rate-limited), (overloaded), (server error), (timed out) 및 (connection failed)입니다. (timed out) 또는 (connection failed)가 반복되면 연결을 확인하세요. API에 연결할 수 없음을 참조하세요. v2.1.229 이전에는 메시지가 범주를 명시하지 않았고 Wait briefly and then try this action again으로 읽혔습니다.
맞는 범주가 없으면 메시지는 괄호에 범주 없이 나타납니다. 둘 이상의 실패가 해당 형식을 생성합니다. Amazon Bedrock에서, Mantle 엔드포인트 포함, AWS 계정이 메시지에 명시된 모델을 호출할 수 없을 때도 나타나며, 계정에 모델에 대한 액세스 권한이 부여될 때까지 모든 재시도에서 해당 실패가 반복됩니다.
수행할 작업:
- 몇 초 후 재시도합니다. Claude는 동일한 메시지를 보고 일반적으로 자동으로 재시도합니다. 일시적 실패는 자동 모드 적격성과 무관합니다. 설정을 변경할 필요가 없습니다
- 재시도가 계속 실패하면 읽기 전용 작업을 계속하고 나중에 차단된 작업으로 돌아옵니다
- Amazon Bedrock에서 메시지가 모든 재시도에서 반환되면 계정이 명시된 모델을 호출할 수 있는지 확인합니다: 표준 Amazon Bedrock 모델의 경우 IAM 정책이 호출을 허용하는지 확인합니다. Mantle 모델 ID의 경우 AWS 계정 팀에 문의합니다
- 메시지가 모든 재시도에서 반환되고
CLAUDE_CODE_AUTO_MODE_MODEL에 설정한 모델을 명시하는 경우, 세션이 실행되는 API 또는 클라우드 제공자가 해당 모델 ID를 제공하는지 확인합니다. 제공하지 않으면 변수를 해당 제공자가 제공하는 모델 ID로 설정하거나, 변수를 해제하여 기본 분류기 모델을 사용합니다.
- 작업을 재시도합니다. 이는 일반적으로 다음 시도에서 성공합니다
claude --debug를 실행하고 작업을 반복하여 디버그 로그에서 세부 정보를 확인합니다
-p 실행에서 Claude Code는 실행을 중지하지 않습니다. Claude가 수신하는 내용은 작업을 요청한 위치에 따라 다릅니다:
-p실행 중--input-format stream-json없이 백그라운드 서브에이전트에 Claude Code는Agent aborted: auto mode classifier request refused by the safety safeguard in headless mode를 포함하는 오류 결과를 반환합니다- 대화형 세션 및
-p실행의 주 대화를 포함한 다른 모든 곳에서 Claude Code는 해당 거부를 Claude에게 반환합니다
- 이것은 작업에 대한 결정이 아닙니다. 대화에 이미 있는 내용이 자동 모드가 대화를 분류기에 보낼 때 API의 안전 필터를 트리거했습니다
- 재시도는 도움이 되지 않습니다. 동일한 대화 내용이 필터를 다시 트리거합니다
- 대화형 세션에서 다른 권한 모드로 전환하여 확인 요청이 표시될 때 작업을 승인할 수 있습니다
- 트리거 내용 없이 새 대화를 시작합니다
- 대화형 세션에서 자동 모드는 해당 작업에 대해 일반 권한 프롬프트로 폴백하므로 수동으로 승인하거나 거부할 수 있습니다
- 비대화형
-p실행 중--input-format stream-json없이 백그라운드 서브에이전트에 Claude Code는Agent aborted: auto mode classifier transcript exceeded context window in headless mode를 포함하는 오류 결과를 반환하고 실행을 계속합니다 --permission-prompt-tool없이-p실행의 다른 곳에서 폴백할 프롬프트가 없으므로 작업이 실행되지 않고 실행이 계속됩니다
- 대화형 세션에서 나타나는 프롬프트에서 작업을 승인하거나 거부합니다
- 대화형 세션에서
/compact를 실행하여 대화 크기를 줄여 후속 작업이 분류기 윈도우에 다시 맞도록 합니다
서버가 안전 판정을 반환하지 않음
서버 측 분류기 검토 하에서 자동 모드는 서버가 판정을 제공하지 않을 때 작업을 거부합니다. 거부는 Claude Code가 하나를 결정할 수 있을 때 괄호에 범주를 명시합니다. 예를 들어(timed out):
Auto mode check unavailable을 카운트다운과 함께 표시하며, Esc를 누르면 턴이 중단됩니다.
10개 응답이 연속으로 판정이 없으면 자동 모드는 턴을 중지합니다:
- 대화형 세션에서 메시지는 트랜스크립트에 경고로 나타나고 턴이 끝납니다
- 비대화형
-p실행에서 실행이 끝나고 실행 오류를 보고합니다. 기본 텍스트 출력을 사용하면 메시지가 stderr에 인쇄됩니다. - 서브에이전트가 한도에 도달했을 때 서브에이전트는 완료 전에 중지되고 Claude는 자동 모드가 중지했다는 메모와 함께 서브에이전트가 생성한 것을 받습니다
- 대화형 세션에서
Ctrl+O를 눌러 트랜스크립트 뷰어에서 거부 텍스트를 확인합니다. - 거부가
(the conversation is too long for the check)를 명시하면 Claude Code 프롬프트에서/compact를 실행하여 대화를 줄입니다. 대화가 짧아질 때까지는 다른 메시지를 보내도 동일한 거부를 받습니다. 자동 압축을 끈 경우 다시 켜서 다음에는 Claude Code가 자체적으로 압축하도록 합니다. - 다른 메시지를 보내 Claude가 다시 시도하도록 합니다. 응답 수 계산이 다시 시작됩니다.
- 중지가 반복되고 요청이 LLM 게이트웨이 또는 프록시를 통과하면 스트리밍 응답을 자르거나 다시 쓰는지 확인합니다. 서버 측 분류기 검토는 어떤 게이트웨이 동작이 거부를 유발하는지 설명하며, 게이트웨이 호환성 가이드는 변경되지 않은 상태로 통과시켜야 할 내용을 나열합니다.
- Claude Code를 시작하기 전에
CLAUDE_CODE_AUTO_MODE_SERVER=0을 설정하여 대신 자체 분류기 요청을 사용합니다. v2.1.281 이전에는 Claude Code가 Anthropic API에 대한 직접 연결에서 변수를 읽지 않았습니다. - 대신 작업을 직접 승인하려면 자동 모드에서 전환합니다
a hook changed this call's input after auto mode reviewed it
이 거부는 서버가 검토한 후 훅 또는 mod가 호출의 입력을 변경했기 때문에 검토가 실제로 실행될 내용을 다루지 않는다는 의미입니다. 작업이 안전하지 않다는 판단이 아닙니다.
동일한 Claude 응답의 이후 호출도 다음 사유로 거부될 수 있습니다:
- 변경 중지: 해당 호출 또는 동일한 Claude 응답의 이전 호출을 변경한 훅 또는 mod를 끄거나 관리자에게 끄도록 요청합니다. 훅을 찾으려면 Claude Code 프롬프트에서
/hooks를 실행합니다. 터미널 세션에서는/plugin을 실행하여 활성 mod를 확인합니다. - 호출 직접 승인: Manual 모드로 전환합니다
Was not reviewed and did not run
was not reviewed and did not run 거부는 대화가 너무 길어 자동 모드 분류기가 작업을 검사할 수 없으므로 작업이 실행되지 않았음을 의미합니다. Claude Code는 Claude에게 다음 메시지를 반환합니다:
gave no verdict (the conversation is too long for the check)거부Auto mode classifier transcript exceeded context window메시지
- 메시지가 알리는 압축이 성공하면 아무것도 할 필요가 없습니다.
- 두 메시지 중 하나가 표시되면 Claude Code 프롬프트에서
/compact를 실행하여 직접 대화를 줄입니다. 자동 압축을 끈 경우 다시 켜서 다음에는 Claude Code가 자체적으로 압축하도록 합니다.
API 오류로 인해 에이전트가 조기에 종료됨
서브에이전트의 API 요청이 사용 한도에 도달했거나 서버 오류에 대한 재시도가 소진되는 등의 이유로 최종적으로 실패했으므로 서브에이전트가 작업을 마치기 전에 중지했습니다. 이 메시지는 Claude Code v2.1.199 이상이 필요합니다. 그 이전에는 API 오류 텍스트가 서브에이전트의 결과인 것처럼 Claude에게 반환되었습니다.- 콜론 뒤의 오류 세부 정보를 이 페이지의 해당 섹션(예: 사용 한도 또는 서버 오류)과 대조하고 해당 섹션의 단계를 따릅니다
- 기본 오류가 해결되면 Claude에게 작업을 재시도하거나 서브에이전트를 재개하도록 요청합니다
사용 한도
이 섹션의 오류 대부분은 계정이나 플랜에 연결된 할당량에 도달했음을 의미합니다. 세 가지는 다르게 작동합니다.Server is temporarily limiting requests는 플랜 할당량과 관계없는 서버 측 스로틀이고, Usage credits required for 1M context는 할당량 소진이 아니라 이용 자격 확인이며, The prompt to confirm went unanswered는 할당량 도달 여부와 관계없이 사용량 크레딧 동의 프롬프트가 응답 없이 닫혔음을 의미합니다.
You’ve hit your session limit
구독 플랜에는 일정 기간 단위로 갱신되는 사용 허용량이 포함되어 있습니다. 허용량이 소진되면 다음 메시지 중 하나가 표시됩니다./model로 해당 제품군 외의 모델로 전환하면 작업을 계속할 수 있습니다.
claude.ai 구독으로 로그인한 대화형 세션에서는 Claude Code가 열린 세션에서 대기하다가 재설정 직후 중단된 작업을 계속할 수도 있습니다. 표시되는 내용, 대기를 시작하거나 취소하는 방법, 자동 계속을 끄는 방법은 사용 한도 재설정 대기를 참조하세요. v2.1.234 이전에는 Claude Code가 이 대기 기능을 제공하지 않았습니다.
사용량은 세션 허용량과 주간 허용량에 동시에 집계됩니다. 대규모 워크플로 팬아웃과 같은 단일 고강도 활동으로 세션 윈도우가 재설정되기 전에 주간 허용량이 소진될 수 있습니다.
해결 방법:
- 오류에 표시된 재설정 시간까지 기다립니다
- Desktop 앱의 Code 탭에서는 세션 한도 카드에 Auto-continue when limits reset 체크박스가 제공됩니다. 주간 한도 카드에는 제공되지 않습니다. 이 옵션을 선택하면 Desktop 앱이 재설정 후 중단된 턴을 재시도하며 카드에 재시도 시간을 표시합니다. Desktop 체크박스와 CLI의
/config에 있는 Continue automatically at usage limit 설정은 별개이므로 각각 따로 꺼야 합니다. - Opus 또는 Sonnet 한도의 경우
/model을 실행하고 해당 제품군 외의 모델로 전환하여 작업을 계속합니다. 각 모델에는 자체 프롬프트 캐시가 있으므로 다음 요청은 캐시 적중 없이 전체 대화를 다시 읽습니다. 모델 전환을 참조하세요 /usage를 실행하여 플랜 한도와 재설정 시간을 확인합니다/usage-credits를 실행하여 Pro, Max 및 Ultra에서는 추가 사용량을 구매하거나, Team 및 Enterprise에서는 관리자에게 요청합니다. 청구 방식은 유료 플랜의 사용량 크레딧을 참조하세요.- 더 높은 기본 한도를 위해 플랜을 업그레이드하려면 claude.com/pricing을 참조하세요
You've used 85% of your session limit · resets 3:45pm과 같은 메시지로 대부분을 사용했다고 경고할 수 있습니다. 남은 허용량을 확인하려면 사용자 지정 상태줄에 rate_limits 필드를 추가하거나, Desktop 앱에서 사용량 링을 클릭하세요.
Usage credits required for 1M context
선택한 모델이 100만 토큰 확장 컨텍스트 윈도우를 사용하며, 사용자의 플랜에서는 사용량 크레딧을 통해서만 이를 이용할 수 있습니다./compact를 포함한 모든 후속 요청에서 오류가 반복되었습니다. 해당 버전에서는 /clear를 실행하여 복구하세요. 아래 단계는 [1m] 모델을 명시적으로 선택한 경우에 적용됩니다.
해결 방법:
/model을 실행하고[1m]접미사가 없는 변형을 선택하여 표준 컨텍스트 윈도우로 되돌립니다- 메시지에
/usage-credits가 언급된 경우, 이를 실행하여 Pro, Max, Ultra에서는 100만 변형에 대한 종량제 청구를 켜거나, Team 및 Enterprise에서는 관리자에게 사용량 크레딧을 요청합니다. 사용량 크레딧이 켜지면 메시지 안내에 따라 Claude Code를 다시 시작하거나 새 세션을 시작합니다. 그때까지 세션은 표준 컨텍스트 한도로 유지됩니다. /model이후에도 오류가 계속되면 100만 모델 ID가 다른 곳에 설정되어 있을 수 있습니다. 우선순위에 따라 확인할 구성 위치는 모델 설정을 참조하세요.- 모델 선택기에서 100만 변형을 완전히 제거하려면
CLAUDE_CODE_DISABLE_1M_CONTEXT=1을 설정합니다
run /usage-credits to turn them on, or /model to switch to standard context로 끝났으며 다시 시작에 대한 언급이 없었습니다.
The prompt to confirm went unanswered
Fable 사용량 크레딧 동의 프롬프트가 아무도 응답하지 않은 채 닫히면, Claude Code는 다음 메시지 중 하나와 함께 턴을 종료합니다.continuing on Fable 5.2 및 Fable 5.2 now uses usage credits로 표시됩니다. Remote Control이 연결된 경우에는 각 메시지가 대신 Claude stopped here · send a message to be asked again, or switch models로 끝날 수 있습니다. v2.1.257 이전에는 첫 번째 메시지가 Fable 5 limit reached로 시작했습니다.
이는 Remote Control 세션, 백그라운드 세션, 에이전트 팀 팀원 세션, 그리고 다른 애플리케이션이 Agent SDK를 통해 호스팅하는 세션에서 발생합니다. Claude Code가 프롬프트를 닫는 시점은 Fable 및 사용량 크레딧을 참조하세요.
해결 방법:
- 세션이 실행되는 곳, 즉 터미널이나 세션을 호스팅하는 애플리케이션에서 다른 프롬프트를 보내고 동의 프롬프트가 다시 표시되면 응답합니다. 백그라운드 세션의 경우 먼저 에이전트 뷰에서 해당 세션에 연결합니다. 메시지에
Claude stopped here가 표시되면 연결된 기기에서 답장하고 그곳에서 동의 프롬프트에 응답할 수도 있습니다. /model을 실행하여 사용량 크레딧이 청구되지 않는 모델로 전환합니다- 더 많은 시간을 확보하려면
dialogExpiry를 더 긴 값이나"never"로 설정합니다
Server is temporarily limiting requests
API가 플랜 할당량과 관계없는 단기 스로틀을 적용했습니다.- 잠시 기다린 후 다시 시도합니다
- 문제가 지속되면 status.claude.com을 확인합니다
Request rejected (429)
API 키, Amazon Bedrock 프로젝트 또는 Google Cloud 프로젝트에 구성된 속도 제한에 도달했습니다.ANTHROPIC_BASE_URL을 사용하는 경우 게이트웨이 호스트를 안내합니다.
Claude Code와 API 사이의 프록시, 로드 밸런서 또는 게이트웨이가 자체 HTML 429 페이지로 응답하면, · 뒤의 텍스트는 해당 페이지에 제목이 있는 경우 Too Many Requests와 같은 페이지 제목이 됩니다. v2.1.281 이전에는 · 뒤에 페이지 전체 마크업이 출력되었습니다.
해결 방법:
/status를 실행하여 활성 자격 증명이 예상한 것인지 확인합니다. 환경에 남아 있는ANTHROPIC_API_KEY로 인해 요청이 구독 대신 낮은 등급의 키를 통해 라우팅될 수 있습니다.- 제공업체 콘솔에서 활성 한도를 확인하고 필요하면 더 높은 등급을 요청합니다
- Anthropic API 키의 경우 등급 작동 방식과 워크스페이스별 상한 설정 방법은 속도 제한 참조를 확인하세요
- 동시성을 줄입니다. 많은 서브에이전트를 병렬로 실행하지 않거나, 대량 스크립트 실행 시
/model로 더 작은 모델로 전환합니다
You’ve hit your monthly spend limit
플랜에 포함된 사용량으로 이 요청을 처리할 수 없으며, 그 대신 비용을 지불할 사용량 크레딧이 지출 한도에 도달했습니다. 플랜의 사용 윈도우 중 하나가 소진되었거나, 요청 비용을 사용량 크레딧으로만 지불하는 경우 플랜으로 요청을 처리할 수 없습니다. 예를 들어 사용량 크레딧으로 청구되는 모델에 대한 요청이 이에 해당합니다.· 앞의 문구는 조직의 월간 지출 한도처럼 사용자를 차단한 한도를 나타내고, 뒤의 텍스트는 해당 한도를 늘리는 방법을 안내합니다. 클라우드 세션이나 Remote Control에서는 이 텍스트에 URL이 포함되지 않으며, 사용자 본인의 monthly spend limit에 대한 메시지는 한도를 늘리는 방법을 안내하지 않습니다. 다른 세션에서는 다음과 같은 형태로 표시됩니다.
team's shared budget은 관리자가 사용자가 속한 그룹에 할당한 공동 예산이며, 메시지에는 그룹 이름이 표시되지 않습니다. channel's monthly spend limit은 세션이 실행되는 특정 Slack 채널 하나의 예산이므로, 조직에는 그 외의 예산이 남아 있을 수 있습니다.
플랜의 윈도우 중 하나가 소진된 경우에는 메시지에 · your session limit resets 3:45pm처럼 해당 윈도우의 재설정 시간도 표시되며, 누군가 한도를 늘리지 않아도 그 시점에 접근이 복원됩니다. 사용량 기반 청구를 사용하는 조직에서는 You've hit your individual usage limit처럼 메시지에 spend limit 대신 usage limit이 표시됩니다.
Claude apps 게이트웨이를 통해 연결하고 소문자로 된 spend limit reached가 표시된다면, 이는 게이트웨이 운영자가 설정한 상한입니다. Spend limit reached를 참조하세요.
해결 방법:
- Pro, Max, Ultra에서는 claude.ai의 Settings > Usage에서 월간 지출 한도를 늘리거나
/usage-credits를 실행합니다 - Team 및 Enterprise에서는 청구를 관리하는 경우 Organization settings > Usage에서 한도를 늘리거나 관리자에게 요청합니다.
/usage-credits는 해당 요청을 관리자에게 대신 보냅니다 - 채널 한도의 경우 조직 소유자나 채널 관리자에게 claude.ai에서 한도를 늘려 달라고 요청합니다. Claude Tag 문서의 채널별 한도를 참조하세요
- 메시지에 플랜 윈도우의 재설정 시간이 표시되어 있다면 그때까지 기다릴 수도 있습니다
/usage를 실행하여 플랜의 윈도우와 각 윈도우의 재설정 시간을 확인합니다
Spend limit reached
Claude apps 게이트웨이를 통해 연결하고 있으며 게이트웨이 운영자가 설정한 지출 상한에 도달했습니다. 게이트웨이는 운영자가 상한을 늘릴 때까지, 또는 상한이 $0보다 큰 경우 상한이 재설정될 때까지 요청을 차단합니다. 차단된 각429 응답에 x-should-retry: false를 표시하므로, 터미널에서 Claude Code는 재시도 없이 이 메시지를 표시합니다.
- 날짜가 있는 경우: 상한이 해당 날짜 00:00 UTC에 재설정됩니다
- 날짜가 없는 경우: 상한이 $0이거나, 게이트웨이가 v2.1.225 이전 버전을 실행 중입니다
spend limit reached (daily; resets 2026-08-09 00:00 UTC)처럼 메시지에 상한의 기간과 재설정 시간이 표시되었습니다.
해결 방법:
- 메시지에 날짜가 있으면 재설정을 기다리거나, 메시지에 운영자 안내가 있는 경우 그 안내를 따릅니다
- 메시지에 날짜가 없거나, 해당 날짜 이후에도 계속 차단되거나, 상한에 자주 도달하는 경우 게이트웨이 운영자에게 상한을 늘려 달라고 요청합니다
This request exceeds your group's budget은 그룹의 공동 예산이 소진되었음을 의미합니다. 메시지에 안내된 단계를 따르세요.
spend limit unavailable은 게이트웨이가 지출 기록을 읽을 수 없어 상한 초과 때문이 아니라 예방 차원에서 요청을 차단했음을 의미합니다. 보통 저절로 해결되며, 문제가 지속되면 게이트웨이 운영자에게 알리세요.
Credit balance is too low
Console 조직의 선불 크레딧이 소진되었거나, 구독을 사용하려 했는데 Claude Code가 Console API 키로 요청을 보내고 있습니다.- Pro, Max, Ultra, Team 또는 Enterprise 플랜을 사용 중인데 이 메시지가 표시된다면
/status를 실행하고API key행을 확인합니다. 환경에 승인된ANTHROPIC_API_KEY가 있으면 요청이 구독 대신 해당 키를 통해 라우팅됩니다. 현재 셸에서 설정을 해제하고 셸 프로필에서 제거한 다음claude를 다시 실행합니다. 아직 구독으로 로그인하지 않았다면/login을 실행합니다. - platform.claude.com/settings/billing에서 크레딧을 추가하고, 잔액이 0이 되기 전에 충전되도록 자동 충전을 활성화하는 것을 고려합니다
- 단일 프로젝트가 조직 잔액을 소진하지 않도록 Console에서 워크스페이스별 지출 상한을 설정합니다. 효과적인 비용 관리를 참조하세요.
Could not update your spend limit
지출 한도에 도달했을 때 표시되는 프롬프트에서 변경한 지출 한도를 서버가 거부했습니다.Could not update your spend limit. Press Enter to retry.로 표시되며 재시도하면 성공할 수 있습니다. v2.1.216 이전에는 Claude Code가 모든 실패에 일반 형태를 표시했습니다.
한도를 제거하는 경우, v2.1.327 이상에서는 일반 형태가 Could not remove your spend limit로 시작합니다.
해결 방법:
- 메시지에 이유가 포함되어 있으면 더 낮은 금액처럼 그 조건을 충족하는 한도를 선택합니다
- 메시지가 일반 형태만 표시하면 재시도합니다. 일시적인 실패일 수 있습니다
- 변경이 계속 실패하면 대신 브라우저의 claude.ai 청구 설정에서 변경합니다
인증 오류
이 오류는 Claude Code가 API에 사용자의 신원을 증명할 수 없다는 뜻입니다. 언제든/status를 실행하면 현재 활성화된 자격 증명을 확인할 수 있습니다.
Not logged in
이 세션에서 사용할 수 있는 유효한 자격 증명이 없습니다.Authentication required · Sign in again to continue로 표시되며, 앱에서 다시 로그인합니다.
같은 구성 디렉터리를 사용하는 다른 Claude Code 창에서 claude.ai 계정으로 로그인하면, 이 메시지를 표시하는 대화형 세션이 자동으로 해당 로그인을 사용하기 시작합니다. 세션을 다시 시작할 필요가 없습니다.
macOS의 v2.1.286 이전 버전에서는 다른 창에서 로그인한 후에도 세션에 이 메시지가 계속 표시될 수 있었습니다. 해당 버전에서는 메시지를 표시하는 세션을 다시 시작하세요.
해결 방법:
/login을 실행하여 Claude 구독 또는 Console 계정으로 인증합니다- 환경 변수로 인증될 것으로 예상했다면
claude를 실행한 셸에서ANTHROPIC_API_KEY가 설정되고 export되었는지 확인합니다 - 대화형 로그인이 불가능한 CI 또는 자동화 환경에서는 시작 시 키를 가져오는
apiKeyHelper스크립트를 구성합니다 - 누군가 같은 claude.ai 계정과 조직에 다시 로그인할 때
claude -p작업이 이 메시지와 함께 종료된다면, 해당 로그인이 실행되는 곳의 Claude Code를 업데이트합니다. v2.1.318 이전에는 Claude Code가 해당 로그인 중에 새 로그인을 저장하기 전에 저장된 로그인을 제거했습니다. - 여러 자격 증명이 있을 때 Claude Code가 어떤 자격 증명을 사용하는지 알아보려면 인증 우선순위를 참조합니다
Could not resolve authentication method
세션이 자격 증명 없이 API 클라이언트에 도달했습니다. 백그라운드 세션과 클라우드 세션은 워커가 자격 증명 없이 시작될 때 이 메시지를 표시합니다. 대화형,-p, Agent SDK 실행은 같은 상태를 Not logged in으로 보고하고 이 문자열은 디버그 로그에만 기록하므로, 로그에서 이 문자열을 발견했다면 해당 항목을 따릅니다.
- 백그라운드 또는 클라우드 세션에서 이 메시지가 나타나고 자격 증명이 이미 구성되어 있다면 v2.1.176 이상으로 업그레이드합니다
ANTHROPIC_API_KEY,CLAUDE_CODE_OAUTH_TOKEN또는 클라우드 공급자 자격 증명이 대화형 셸뿐 아니라 워커를 실행하는 환경에도 설정되어 있는지 확인합니다- Agent SDK의 경우 빠른 시작의 인증 설정을 참조합니다
- 같은 환경의 대화형 세션에서
/status를 실행하여 어떤 자격 증명 소스가 확인되는지 확인합니다
Invalid API key
ANTHROPIC_API_KEY 환경 변수 또는 apiKeyHelper 스크립트가 API에서 거부한 키를 반환했거나, Claude Code가 ANTHROPIC_API_KEY의 키를 전송하기 전에 차단했습니다.
Fix external API key 뒤에 Invalid X-Api-Key header value from ANTHROPIC_API_KEY: it contains a line break at character 41 (120 characters on 2 lines). 같은 설명으로 이어지면 API는 키를 전혀 받지 않은 것입니다. Claude Code가 HTTP 헤더에 담을 수 없는 문자를 발견하고 전송 전에 요청을 중단했습니다. 설명을 읽고 값을 수정하는 방법은 Invalid request header value를 참조합니다.
해결 방법:
- 오타가 있는지 확인하고 Console에서 키가 취소되지 않았는지 확인합니다
- 같은 셸에서
env | grep ANTHROPIC을 실행하거나 PowerShell에서는Get-ChildItem Env:ANTHROPIC*를 실행합니다. direnv, dotenv 셸 플러그인, IDE 터미널 같은 도구는 사용자가 명시적으로 설정하지 않아도 프로젝트의.env파일에서 오래된 키를 불러올 수 있습니다. ANTHROPIC_API_KEY설정을 해제하고/login을 실행하여 대신 구독 인증을 사용합니다- 키가
apiKeyHelper스크립트에서 오는 경우 스크립트를 직접 실행하여 stdout에 유효한 키를 출력하는지 확인합니다 /status를 실행하여 Claude Code가 실제로 사용 중인 자격 증명 소스를 확인합니다
Your apiKeyHelper script is failing
Claude Code가apiKeyHelper 설정의 명령을 실행했지만 키를 돌려받지 못했습니다. 키가 없으면 요청이 자리 표시자 자격 증명과 함께 API에 도달하고, API는 401로 이를 거부합니다. 터미널의 Authentication 패널에 다음 중 어떤 일이 발생했는지 표시됩니다:
- 명령이 오류와 함께 종료되었거나 시간 초과되었습니다
- 명령이 stdout에 아무것도 출력하지 않았습니다
- 명령이 로그인 배너나 로그 줄처럼 키 이외의 내용을 출력했습니다. 패널은 출력을 반복하지 않고
returned output that cannot be used as an API key를 표시하며 무엇이 잘못되었는지 알려줍니다. v2.1.227 이전에는 Claude Code가 명령이 출력한 내용을 앞뒤 공백만 제거한 후 그대로 전송했습니다.
apiKeyHelper failed: 접두사와 함께 구체적인 이유가 출력됩니다.
Claude Code는 이 메시지를 표시하기 전에 스크립트를 다시 실행하고 요청을 최대 두 번 더 재시도하므로, 실패는 세 번의 시도 안에 드러납니다. v2.1.208 이전에는 Claude Code가 전체 재시도 한도를 소진하며 자리 표시자 자격 증명으로 요청을 다시 보낸 후, 스크립트 실패 대신 일반적인 401 인증 오류를 보고했습니다.
여기서는 /login을 실행해도 도움이 되지 않습니다. 설정이 존재하는 한 헬퍼의 출력이 저장된 로그인보다 우선 적용되기 때문입니다.
해결 방법:
apiKeyHelper에 구성된 명령을 셸에서 직접 실행하여 실패를 재현합니다- 명령이 세션 만료를 보고하면 자격 증명 공급자에서 다시 인증합니다. 예를 들어 SSO 또는 시크릿 볼트에 다시 로그인합니다
- 명령이 키만 stdout에 출력하고 종료 코드 0으로 종료되도록 수정합니다. 키는 최대 16,384자의 출력 가능한 ASCII로 된 단일 토큰이어야 합니다. 작동하는 설정은 apiKeyHelper로 자격 증명 교체를 참조합니다.
/status를 실행하여 실패를 확인하고apiKeyHelper가 활성 자격 증명 소스인지 확인합니다.apiKeyHelper행에는 종료 코드와 명령의 오류 출력 같은 마지막 실패의 세부 정보와 함께Failing이 표시되며, 다음에 성공적으로 실행되면 사라집니다. v2.1.274 이전에는/status에 실패가 아닌 자격 증명 소스만 표시되었습니다.- 명령이 실패할 때마다 종료 코드와 오류 출력이 터미널의
Authentication패널에도 표시됩니다. v2.1.212 이전에는 패널 제목이Cloud authentication이었습니다.
Claude Code didn’t send your claude.ai login
다음 메시지는 Claude Code가 요청을 거부하고 claude.ai 로그인을 전송하지 않았다는 뜻입니다:Your organization's settings need an update: 관리자에게 API 키 헬퍼 구성을 수정해 달라고 요청합니다- 머신에 어떤 관리형 소스가 있는지 관리자에게 알려주려면 Claude Code 프롬프트에서
/status를 실행하고Setting sources줄을 복사합니다.Skipped sources줄이 나타나면 그것도 복사합니다 - 사용자가 설정을 관리하고 헬퍼가 머신의 관리형 설정 파일 또는 MDM 정책에 있다면 머신의
apiKeyHelper가 적용되지 않는 경우를 참조합니다
- 머신에 어떤 관리형 소스가 있는지 관리자에게 알려주려면 Claude Code 프롬프트에서
Couldn't load your organization's settings: 연결을 확인한 후 Claude Code를 다시 시작합니다. 다시 시작한 후에도 메시지가 다시 나타나면 관리자에게 알립니다Restart Claude Code to finish signing in: Claude Code를 다시 시작합니다
Claude Code didn't send your claude.ai login으로 시작하는 하나의 메시지가 출력되었습니다.
Invalid request header value
Claude Code가 요청 헤더로 보내려던 값에 HTTP 헤더가 담을 수 없는 문자가 포함되어 있습니다. 이는 줄바꿈, NUL 바이트, 또는 둥근 따옴표나 폭 없는 공백(zero-width space)처럼U+00FF보다 큰 문자입니다. Claude Code는 아무것도 전송하기 전에 요청을 중단하고 수정할 변수나 설정의 이름을 알려줍니다. 일반적인 원인은 보이지 않는 문자나 불필요한 줄바꿈이 포함된 문서나 채팅에서 붙여넣은 자격 증명입니다.
Claude Code는 Claude API에 직접 또는 LLM 게이트웨이를 통해 요청을 보낼 때 이 검사를 실행합니다. Amazon Bedrock 같은 서드파티 클라우드 공급자에서는 Claude Code가 전송 전에 이 검사를 실행하지 않습니다.
Invalid auth token:ANTHROPIC_AUTH_TOKEN또는CLAUDE_CODE_OAUTH_TOKEN의 bearer 토큰Invalid ANTHROPIC_CUSTOM_HEADERS:ANTHROPIC_CUSTOM_HEADERS에 설정한 헤더 이름 또는 값. 설명은 이름이나 값을 반복하지 않고distinct header 2 of 3 parsed from ANTHROPIC_CUSTOM_HEADERS처럼 몇 번째Name: Value쌍에 문제가 있는지 알려줍니다. 이름과 값은 모두 사용자가 직접 정한 것이기 때문입니다.Invalid request header from the environment: Claude Code가CLAUDE_AGENT_SDK_CLIENT_APP같은 다른 환경 변수에서 요청 헤더로 복사하는 값. 설명에 수정할 변수의 이름이 표시됩니다.
ANTHROPIC_API_KEY를 같은 뒷부분 설명과 함께 Invalid API key로 보고합니다. 저장된 /login 자격 증명이 잘못된 경우에는 대신 Not logged in으로 보고하므로, /login을 실행하여 새 자격 증명을 저장합니다. apiKeyHelper 스크립트의 출력은 이 검사에 도달하지 않습니다. Claude Code는 스크립트가 실행될 때 출력을 검증하며, HTTP 헤더가 담을 수 없는 출력은 Your apiKeyHelper script is failing으로 실패합니다.
두 번째 · 뒤에서 메시지는 문제를 설명합니다. 다음은 전체 예시입니다:
a non-ASCII character로 보고합니다.
해결 방법:
- 메시지에 표시된 변수나 설정을 다시 설정하되, 같은 소스에서 다시 붙여넣지 말고 보고된 위치 주변의 문자를 직접 다시 입력합니다
ANTHROPIC_CUSTOM_HEADERS의 경우 한 줄에Name: Value쌍을 하나씩 두고 메시지가 지목한 쌍을 다시 작성합니다/status를 실행하여 활성 자격 증명 소스를 확인합니다
This organization has been disabled
Claude Code가 비활성화된 Console 조직의 오래된ANTHROPIC_API_KEY를 사용하고 있습니다. 저장된 구독 로그인이 있으면 이 키가 로그인보다 우선합니다.
· 뒤의 힌트는 저장된 자격 증명에 따라 달라집니다. 첫 번째 형태는 키 설정을 해제한 후 저장된 /login이 대신 사용될 수 있을 때 나타나고, 두 번째 형태는 키가 유일한 자격 증명일 때 나타납니다.
셸 프로필에서 키를 export하거나 .env에서 불러오면, 정상적으로 작동하는 Pro, Max 또는 Ultra 구독이 있더라도 Claude Code는 /login 대신 해당 키를 사용합니다. 비대화형 모드(-p)에서는 키가 있으면 항상 키가 사용됩니다.
해결 방법:
- 현재 셸에서
ANTHROPIC_API_KEY설정을 해제하고 셸 프로필에서 제거한 후claude를 다시 실행합니다 - 메시지에
Update or unset이 표시되면 대신 사용할 저장된 로그인이 없는 것입니다. 키 설정을 해제하고/login을 실행하거나, 활성 Console 조직의 키로 교체합니다. - 이후
/status를 실행하여 활성 자격 증명이 구독인지 확인합니다 - 환경 변수가 설정되어 있지 않은데도 오류가 계속되면 지원팀에 문의하거나 다른 계정으로 로그인합니다.
Your organization has disabled API key authentication
이 메시지는 Claude Code v2.1.169 이상이 필요합니다. Console 조직의 관리자가 API 키 인증을 꺼 두었으므로 API가 Claude Code가 보내는 키를 거부합니다.· 뒤의 복구 힌트는 키의 출처에 따라 다릅니다:
apiKeyHelper는 /login보다 우선하므로, 둘 중 하나가 여전히 키를 제공하는 동안에는 /login만 실행해서는 도움이 되지 않습니다. 인증 우선순위를 참조합니다.
해결 방법:
- 메시지에
ANTHROPIC_API_KEY가 표시되면 현재 셸에서 설정을 해제하고 셸 프로필이나.env파일에서 제거한 후claude를 다시 실행합니다 - 메시지에
apiKeyHelper가 표시되면settings.json에서apiKeyHelper설정을 제거합니다 /login을 실행하여 claude.ai 계정으로 로그인합니다- 이후
/status를 실행하여 활성 자격 증명이 API 키가 아닌 구독인지 확인합니다 - 자동화를 위해 API 키 인증이 필요하면 조직 관리자에게 Console에서 다시 활성화해 달라고 요청합니다
Your organization has disabled Claude subscription access
Claude 조직에서 구독 로그인으로 Claude Code에 로그인하는 것을 허용하지 않습니다. 같은 계정으로/login을 다시 실행해도 같은 오류가 반환됩니다.
-p 비대화형 모드에서는 이 오류가 oauth_org_not_allowed 오류 코드로 표시됩니다.
해결 방법:
- 관리자에게 조직의 Claude Code 액세스를 활성화해 달라고 요청합니다
- 구독 대신 Console API 키로 인증합니다. 설정 방법은 Claude Console 인증을 참조합니다.
- 사용자가 관리자인데 액세스를 활성화하는 옵션이 보이지 않으면 Anthropic 지원팀에 문의합니다
Scheduled tasks are off for your organization
조직에서 클라우드 예약 작업이 꺼져 있으므로 예약 작업을 만들거나 실행할 수 없습니다. claude.ai의 메시지는 이를 예약 작업(scheduled tasks) 또는 루틴(routines)이라고 부르며, 뒤에 관리자에 관한 문장이 이어집니다:- Team 또는 Enterprise Owner에게 Organization settings > Capabilities > Remote sessions에서 Scheduled tasks (Was Routines) 또는 Routines 토글을 켤 수 있는지 문의합니다
Remote Control에는 Anthropic API가 필요합니다
세션이 Remote Control에 필요한 Anthropic API와 직접 통신하지 않고 있습니다.- Amazon Bedrock의 경우
CLAUDE_CODE_USE_BEDROCK, Google Cloud의 Agent Platform의 경우CLAUDE_CODE_USE_VERTEX같은CLAUDE_CODE_USE_*공급자 변수 - LLM 게이트웨이나 프록시처럼
api.anthropic.com이외의 호스트를 가리키는ANTHROPIC_BASE_URL. claude.ai로 로그인한 경우에도 해당합니다. v2.1.196 이전에는 사용자 지정 기본 URL이 Remote Control을 차단하지 않았습니다 - 설정된
ANTHROPIC_UNIX_SOCKET. 이 경우 세션은api.anthropic.com대신 로컬 소켓을 통해 요청을 보냅니다 /login을 통해 이루어진 엔터프라이즈 클라우드 게이트웨이 로그인. 이 로그인은 Remote Control을 지원하지 않으며 해제할 변수가 없습니다
CLAUDE_CODE_USE_BEDROCK이나ANTHROPIC_BASE_URL처럼 메시지에 표시된 변수의 설정을 해제하고 세션을 다시 시작하거나, Anthropic API와 직접 통신하는 세션에서 Remote Control을 시작합니다- 셸에 변수가 설정되어 있지 않다면 모든 세션에 환경 변수를 적용하는 설정 파일의
env키를 확인합니다 - 이 메시지와 기타 Remote Control 시작 메시지는 Remote Control 문제 해결을 참조합니다
Remote Control이 로그인을 갱신하지 못함
Claude Code는 저장된 claude.ai 로그인을 사용해 얻고 갱신하는 단기 자격 증명으로 실시간 Remote Control 연결을 실행합니다. claude.ai가 해당 로그인을 더 이상 허용하지 않거나 Claude Code에 저장된 로그인이 남아 있지 않으면, Claude Code는 Remote Control을 중지하며 사용자가 다시 로그인해야 합니다. 두 실패 모두 Claude Code가 아직 연결 중일 때 또는 나중에 자격 증명을 갱신할 때 발생할 수 있습니다. Claude Code가 로그인 서비스에 저장된 로그인 갱신을 요청했는데 응답을 받지 못하면, Remote Control을 계속 실행하면서 연결의 현재 자격 증명이 아직 유효한 동안 갱신을 다시 시도합니다. Claude Code가 로그인 서비스에 연결할 수 없거나, 요청이 시간 초과되거나, 서비스가 로그인을 거부하지 않은 채 실패하면 갱신에 대한 응답이 없는 것입니다. 해당 자격 증명이 만료될 때까지 로그인 서비스가 여전히 응답하지 않으면 Claude Code는 Remote Control을 중지하고OAuth token refresh failed를 보고합니다.
Claude Code가 Remote Control을 중지하면 경고와 Remote Control disconnected로 시작하는 트랜스크립트 줄에 이유를 표시합니다. 로컬 세션은 Remote Control 없이 계속 실행됩니다. 이 섹션에서는 다음 줄을 다룹니다:
Claude.ai login expired및Claude.ai login was rejected: 저장된 로그인 토큰이 만료되었거나 취소되어 claude.ai가 더 이상 허용하지 않습니다OAuth token unavailable: 연결의 자격 증명을 갱신할 시점에 Claude Code에 저장된 로그인 토큰이 없었습니다OAuth token refresh failed: Claude Code가 다시 연결하는 동안 claude.ai가 저장된 로그인 토큰을 거부했고, 토큰을 갱신해도 새 토큰이 생성되지 않았습니다JWT refresh failed: no OAuth token: Claude Code가 갱신에 사용할 저장된 로그인 토큰을 찾지 못했습니다Signed out of Claude: 예를 들어 다른 터미널에서/logout을 실행하는 등 이 머신에서 로그아웃했으므로, Claude Code에 연결을 갱신할 저장된 로그인이 남아 있지 않습니다
/login을 실행하여 다시 로그인합니다/remote-control을 실행하여 세션을 다시 연결합니다.run /login to restore Remote Control로 끝나는 메시지는 이 단계가 필요하지 않습니다. 로그인하면 Claude Code가 자동으로 다시 연결합니다.
OAuth token refresh failed — run /login to re-authenticate가 OAuth token refresh failed — re-authenticate, then re-enable Remote Control로, JWT refresh failed: no OAuth token — run /login이 no OAuth token available for recovery (code <N>)로 표시되었습니다. Claude.ai login expired, Claude.ai login was rejected, OAuth token unavailable 메시지는 v2.1.225에서 추가되었습니다.
v2.1.238 이전에는 Claude Code가 현재 Signed out of Claude로 표시되는 경우를 JWT refresh failed: no OAuth token — run /login으로 보고했으며, 로그인 갱신에 한 번이라도 응답이 없으면 즉시 Claude.ai login expired — run /login to restore Remote Control과 함께 Remote Control을 중지했습니다.
Remote Control could not renew this computer’s connection
서버가 claude.ai 로그인을 사용해 연결의 자격 증명이 만료되기 전에 갱신할 수 없을 때claude remote-control을 실행 중인 터미널에 이 경고가 표시됩니다. 경고의 마지막 문장은 현재 자격 증명이 얼마나 더 유효한지, 또는 이미 만료되었는지를 알려줍니다:
- 경고가
claude /login을 실행하라고 안내하면 서버를 실행 중인 머신에서 다른 터미널을 열고 그곳에서claude /login을 실행한 후 claude.ai 계정으로 로그인합니다 - 연결의 자격 증명이 만료된 후에도 서버가 여전히 로그인할 수 없으면
Poll: Authentication failed (401)이 포함된 오류를 출력하고 중지됩니다. 경고의 두 번째 문장에 안내된 대로 다시 로그인한 후, 서버가 중지된 터미널에서claude remote-control을 다시 실행합니다.
로그인한 계정이 변경되어 Remote Control이 중지됨
이 머신에서 다른 claude.ai 계정이나 조직으로 로그인하면 Remote Control 세션 중에 Claude Code가 이 줄을 표시합니다. 예를 들어 다른 터미널에서/login을 실행하는 등 Claude Code 세션 외부에서 전환한 경우입니다.
/login으로 로그인한 상태에서 시작한 Remote Control 세션은 시작 당시 로그인되어 있던 claude.ai 계정과 조직에 속합니다.
/remote-control을 실행하여 현재 계정 또는 조직으로 새 Remote Control 세션을 시작합니다- 이전 상태로 되돌리려면
/login을 실행하고 이전 계정 또는 조직으로 다시 로그인합니다. 그런 다음/remote-control을 실행합니다.
Remote Control server rejected the request (HTTP 404)로 실패할 때까지 Remote Control 세션을 연결된 상태로 유지했습니다. 이 실패는 전환 후 몇 시간이 지나서 발생할 수도 있었습니다.
세션을 실행하는 앱이 로그아웃하거나 계정을 전환하여 Remote Control이 중지됨
Claude 데스크톱 앱이나 IDE가 세션을 호스팅하는 경우 Claude Code는/login이 아닌 해당 앱에서 로그인 토큰을 받습니다. claude.ai가 해당 토큰을 거부하면 Claude Code는 앱에 새 토큰을 요청합니다. 앱이 로그아웃되었다고 응답하거나 이제 다른 Claude 계정으로 로그인되어 있다고 응답하면, Claude Code는 Remote Control 세션을 종료하고 앱에 다음 줄 중 하나를 보냅니다:
- 앱이 로그아웃된 경우 앱에 다시 로그인한 후 앱에서 Remote Control을 다시 켭니다
- 앱이 계정을 전환한 경우 Claude Code는 종료된 세션을 새 계정으로 이어갈 수 없습니다. 해당 계정으로 새 Remote Control 세션을 시작합니다.
run /login 메시지를 앱에 보냈습니다.
OAuth token revoked or expired
저장된 로그인이 더 이상 유효하지 않습니다. 토큰이 취소되었다는 것은 모든 곳에서 로그아웃했거나 관리자가 액세스 권한을 제거했다는 뜻이고, 토큰이 만료되었다는 것은 세션 도중 자동 갱신이 실패했다는 뜻입니다. 두 메시지 모두 Claude Code가 보낸 요청에 대해 API가 반환한 거부를 보고합니다. 갱신 실패 후 저장된 로그인이 이미 삭제된 경우에는 대신 Login expired를 참조하세요.CLAUDE_CODE_OAUTH_TOKEN의 장기 토큰으로 인증하는 경우, 해당 토큰이 만료되거나 취소되면 같은 메시지가 표시됩니다.
-p)와 Agent SDK에서는 메시지가 다음과 같이 표시되며, 구조화된 오류 코드는 authentication_failed입니다:
Your account does not have access to Claude. Please login again or contact your administrator.로 표시되었습니다.
해결 방법:
- Claude Code 프롬프트에서
/login을 실행하여 다시 로그인합니다 -p명령이나 Agent SDK 프로그램이 저장된 로그인을 사용한다면, 같은 환경에서claude를 실행하고/login을 완료한 후 명령이나 프로그램을 다시 실행합니다. 대화형으로 로그인할 수 없는 자동화의 경우ANTHROPIC_API_KEY로 인증하거나claude setup-token으로 장기 토큰을 생성합니다.CLAUDE_CODE_OAUTH_TOKEN환경 변수로 인증하는 경우, 요청이 401로 실패한 후에도 Claude Code는 저장된 로그인의 토큰으로 전환하지 않고 사용자가 설정한 값을 계속 보냅니다./status는 이 자격 증명을CLAUDE_CODE_OAUTH_TOKEN이라고 표시된Auth token행으로 보여줍니다.claude setup-token으로 새 토큰을 생성하고 해당 토큰으로 다시 시작하거나, 변수 설정을 해제하고/login을 실행합니다. v2.1.225 이전에는 Claude Code가 세션 도중 변수 값을 저장된 로그인의 단기 액세스 토큰으로 교체할 수 있었으며, 해당 토큰이 만료되면 세션이 다시 401 오류로 실패했습니다.- 실행할 때마다 반복적으로 로그인을 요청받는 경우 문제 해결의 시스템 시계 확인 및 macOS 자격 증명 저장소 복구 단계를 참조합니다
403 Forbidden및 OAuth 브라우저 문제를 포함한 기타 실패는 로그인 및 인증을 참조합니다
API Error: 401 Invalid authentication credentials
API가 자격 증명의 형식은 인식했지만 그 뒤에 있는 계정이나 조직을 거부했습니다. Anthropic은 자격 증명이 최근에 취소되었거나, 조직이 비활성화되었거나 사용자의 액세스 권한을 제거했거나, 계정 자체가 비활성화된 경우 이 메시지를 반환하므로 토큰 만료가 원인은 아닙니다. 자격 증명은 저장된 로그인일 수도 있고 승인된ANTHROPIC_API_KEY일 수도 있으며 해결 방법이 다르므로, 먼저 /status를 실행하여 어느 것이 활성 상태인지 확인합니다.
/status에 사용 중이 아님으로 표시되지 않은API key행이 있으면, 승인된ANTHROPIC_API_KEY가 활성 자격 증명이며 로그인보다 우선하므로/login으로 대체되지 않습니다. Claude Console에서 키를 교체하거나,unset ANTHROPIC_API_KEY(PowerShell에서는Remove-Item Env:ANTHROPIC_API_KEY)를 실행하여 구독으로 돌아갑니다./status에 로그인만 표시되면/login을 한 번 실행합니다. 자격 증명이 취소된 경우 새 로그인이 이를 대체합니다.- 같은 로그인 계정에 대해 같은 메시지가 다시 나타나면 계정이나 조직이 더 이상 활성 상태가 아닙니다.
/status에 표시된 계정과 조직을 확인하고 조직 관리자에게 액세스 권한 복원을 요청합니다. ANTHROPIC_BASE_URL이 LLM 게이트웨이를 가리키는 경우,401뒤의 텍스트는 Anthropic이 아닌 게이트웨이의 메시지이며/login으로 바뀌지 않습니다. 대신 게이트웨이가 기대하는 자격 증명을 수정합니다.- 게이트웨이가 기대하는 자격 증명을 받은 후에도 모든 요청이
401로 실패한다면, 게이트웨이와 그 업스트림이 도구 검색 필드를 허용하는지 확인합니다. 기본적으로 Claude Code는defer_loading도구 필드와tool_reference블록을 이를 활성화하는anthropic-beta헤더와 함께 보냅니다. v2.1.304 이전에는ENABLE_TOOL_SEARCH로 켠 경우를 제외하고 게이트웨이 뒤에서는 도구 검색이 꺼져 있었습니다.
Login expired
Claude Code가 저장된 claude.ai 로그인을 갱신하려 했지만 OAuth 서비스가 저장된 갱신 토큰을 거부했으므로, Claude Code가 저장된 자격 증명을 삭제했습니다. 다른 저장된 자격 증명이 없으면 이후 모델 요청이 다음 메시지와 함께 중지됩니다.-p)와 Agent SDK에서는 메시지가 다음과 같이 표시되며, 구조화된 오류 코드는 authentication_failed입니다:
reached its time limit라고 표시됩니다. or re-authenticate your Anthropic profile로 끝나는 Login expired 메시지에 대해서는 Anthropic profile login expired를 참조하세요.
계정 자체가 정지되어 갱신이 실패한 경우, Claude Code는 대신 Your account is on hold를 표시합니다.
해결 방법:
/login을 실행하여 다시 로그인하세요.- 다른 Claude Code 창에서 claude.ai 계정으로 로그인하는 경우, 이 세션이 언제 자동으로 해당 로그인을 사용하기 시작하는지는 Not logged in을 참조합니다.
- 비대화형 모드에서는 같은 환경에서
claude를 실행하고/login을 완료한 후 명령을 다시 실행합니다. 대화형으로 로그인할 수 없는 자동화의 경우ANTHROPIC_API_KEY로 인증하거나claude setup-token으로 장기 토큰을 생성합니다. - 로그인이 계속 실패하면 로그인 및 인증을 참조합니다
Could not refresh your login because another Claude Code process is refreshing it
이 메시지는 로그인이 거부되었다는 뜻이 아닙니다. 저장된 claude.ai 로그인이 만료되어 갱신이 필요했습니다. 같은 머신의 다른 Claude Code 프로세스가 공유 갱신 잠금을 보유하고 있었거나 잠금을 남겨둔 채 종료되었고, 이 세션이 기다리는 동안 갱신이 진행되지 않았습니다. Claude Code는 요청을 보내기 전에 중단합니다:-p)와 Agent SDK에서는 메시지가 다음과 같이 표시되며, 구조화된 오류 코드는 server_error입니다:
- 1분 후에 다시 시도합니다. 다른 프로세스가 먼저 갱신을 완료하면 이 세션은 갱신된 로그인을 사용합니다.
- 메시지가 계속 나타나면 다른 Claude Code 창과 프로세스를 닫은 후 다시 시도합니다.
- 실행 중인 다른 Claude Code 프로세스가 없는데도 메시지가 나타나면
/login을 실행합니다. 다시 로그인하는 작업은 갱신 잠금을 기다리지 않습니다.
Could not refresh your login: the disk that holds the Claude Code config directory is full
Claude Code 구성 디렉터리가 있는 디스크의 공간을 확보한 후 메시지를 다시 보냅니다. 디스크가 가득 찬 동안에는 새 로그인을 저장할 수 없으므로 다시 로그인해도 도움이 되지 않습니다.CLAUDE_CONFIG_DIR을 설정한 경우를 제외하고 구성 디렉터리는 홈 디렉터리의 ~/.claude입니다.
-p)와 Agent SDK에서는 메시지가 다음과 같이 표시됩니다:
- 스크립트의 경우 해당 스크립트의
claude -p명령을 다시 실행합니다 - 디스크에 이미 여유 공간이 있다면, 디스크 할당량이나 inode가 부족해도 같은 메시지가 나타납니다. 해당 디스크에서 자신의 파일을 삭제합니다. 메시지가 다시 나타나면 큰 파일 몇 개보다 작은 파일 여러 개를 삭제합니다. 각 파일은 크기와 관계없이 inode를 하나씩 차지하기 때문입니다.
Couldn’t save your login
claude.ai로 로그인했지만 Claude Code가 로그인을 자격 증명 저장소에 저장하지 못해 로그인이 완료되지 않았습니다. macOS에서는 같은 세션 중에 Claude Code가 이미 로그인 키체인에서 자격 증명을 읽거나 저장한 후, 예를 들어 절전이나 유휴 상태로 인해 키체인이 잠기면 이런 일이 발생할 수 있습니다.- macOS에서는 로그인 키체인의 잠금을 해제한 후
/login을 다시 실행합니다 - 다른 플랫폼에서는
/login을 다시 실행합니다 - 그래도 로그인이 저장되지 않으면 키체인 잠금 해제 명령과 기타 자격 증명 저장소 복구 단계는 Not logged in or token expired를 참조합니다
Sign in again to take your previous account or API key off the config file
로그인 후 이 경고가 표시되면 이전에 로그인했던 계정이~/.claude.json에 여전히 저장되어 있을 수 있다는 뜻입니다:
~/.claude.json에 남아 있을 수 있습니다.
해결 방법:
- 셸에서
claude auth login을 실행하여 다시 로그인합니다. 그러면 Claude Code가 교체된 계정이나 API 키를 파일에서 제거하는 저장 작업을 다시 시도합니다.
Your account or API key may still be in the config file
/logout 또는 claude auth logout을 실행했고 Claude Code가 이 프로세스에서 로그아웃했지만, ~/.claude.json에 더 이상 계정이 포함되어 있지 않은지 확인하지 못했습니다. 저장이 반영되지 않았거나, 확인을 위해 파일을 다시 읽을 수 없었습니다.
~/.claude.json에 남아 있을 수 있습니다.
해결 방법:
- 셸에서
claude auth logout을 실행하여 저장을 다시 시도합니다. 저장이 완료되면 명령이Successfully logged out from your Anthropic account.를 출력합니다.
Couldn’t start the local listener that receives the browser sign-in
/login, claude auth login 또는 claude setup-token에서 표시되는 다음 메시지는 모두 브라우저가 로그인 결과를 반환하는 127.0.0.1의 포트를 Claude Code가 열 수 없었다는 뜻입니다.
The browser can't return the sign-in to Claude Code automatically로 시작하는 안내가 표시되면, 로그인은 해당 포트 없이 계속 진행됩니다. 브라우저가 열리지 않으며, 대신 로그인할 URL 위에 안내가 표시됩니다:
Couldn't start the local listener가 포함된 메시지가 표시되면 로그인이 중단된 것입니다. 예를 들어 claude auth login에 입력을 파이프로 전달하는 경우 이런 일이 발생합니다:
The browser can't return the sign-in to Claude Code automatically: 먼저 수정할 것은 없습니다. 안내 아래에 표시된 URL을 브라우저에서 열고 로그인합니다. 그러면 브라우저에 코드가 표시됩니다.Paste code here >프롬프트에서 Claude Code에 코드를 붙여넣으면 로그인이 이어서 진행됩니다.Couldn't start the local listener that receives the browser sign-in: 같은 명령을 다시 실행합니다. 같은 방식으로 중단되면 브라우저 대신 토큰이나 API 키로 로그인합니다. 또는claude auth login에 입력을 파이프로 전달했다면, 붙여넣은 코드를 받을 수 있도록 터미널에서 실행합니다.- 브라우저 대신 토큰이나 API 키로 로그인하려면: claude.ai 구독을 사용하는 경우 로그인이 작동하는 머신에서
claude setup-token을 실행합니다. 그런 다음 출력된 토큰을 이 머신의CLAUDE_CODE_OAUTH_TOKEN환경 변수로 설정합니다. 그렇지 않으면ANTHROPIC_API_KEY환경 변수를 Claude Console의 키로 설정합니다. Claude Code가 여러 자격 증명 중 무엇을 선택하는지는 인증 우선순위에서 설명합니다. - 자동 브라우저 반환을 다시 사용하려면: Claude Code가
127.0.0.1에서 수신 대기할 수 있어야 합니다. 샌드박스 안에서 실행되는 경우 샌드박스 정책이 로컬 포트에서의 수신 대기를 허용하는지 확인한 후 다시 로그인합니다. 해당 환경에서 수신 대기가 작동해야 하는데도 안내가 계속 표시되면, 보고서에 환경 세부 정보가 포함되도록/feedback을 실행합니다.
Failed to start OAuth callback server: Failed to start server. Is port 0 in use?와 같았습니다. 해당 버전에서는 Claude Code를 업데이트하고 다시 로그인하거나, 브라우저 대신 토큰이나 API 키로 로그인합니다.
Claude login not accepted
클라우드 세션을 시작하려 했지만 서버가 401로 세션 생성을 거부했습니다. 일반적으로 로그인이 만료되었거나 취소되어, 서버가 이 머신이 보낸 Claude 로그인을 허용하지 않은 것입니다. 서버가 이유를 제공하면 줄의 첫 부분은 서버 자체의 이유입니다. 그렇지 않으면 줄은 다음과 같습니다:/login을 실행하고 로그인을 완료한 후 세션을 다시 시작합니다
Artifacts need a claude.ai login
세션에 아티팩트에 사용할 수 있는 claude.ai 로그인이 없으므로 Claude Code가 아티팩트 게시 또는 읽기를 거부했습니다. 메시지의 모든 형태는 같은 문구로 시작하며, 그 뒤에 세션의 인증 방식에 따라 다른 해결 방법이 이어집니다. 경쟁하는 자격 증명이 없으면 다음과 같이 표시됩니다:/login을 실행하고 Claude account with subscription을 선택합니다. Anthropic Console account 옵션은 claude.ai 자격 증명을 제공하지 않습니다.- 메시지에
ANTHROPIC_API_KEY,apiKeyHelper설정, 이전/login으로 저장된 Console 키처럼 우선하는 자격 증명이 표시되면, 메시지에 안내된 대로 제거한 후/login을 실행합니다 - 메시지에 이 원격 세션이 세션을 시작한 머신을 통해 인증한다고 표시되면, 해당 머신에서 claude.ai에 로그인한 후 세션을 다시 연결합니다
- 메시지에 자격 증명이 세션의 호스트 환경에서 주입된다고 표시되면 해당 세션에서는 변경할 수 없습니다. claude.ai에 로그인된 세션을 시작합니다
- 플랜, 모델 공급자, 조직 정책 등 아티팩트의 기타 요구 사항은 사용 가능 여부를 참조합니다
Administrator policy requires a Cloud gateway sign-in
이 머신에 관리자가 적용한 관리형 설정이forceLoginMethod를 "gateway"로 설정하거나 forceLoginGatewayUrl을 설정했습니다. CLAUDE_CODE_USE_BEDROCK 같은 변수로 클라우드 공급자를 선택한 경우를 제외하고, Claude Code는 Claude apps gateway 로그인만 허용합니다. 다음 두 메시지 중 하나가 표시됩니다:
/login을 실행하지 않았다면, 모델 요청이 이 메시지와 함께 실패합니다.
머신에 Anthropic에서 발급한 자격 증명도 있고 관리형 설정이 forceLoginMethod 또는 forceLoginOrgUUID를 설정한 경우, Claude Code는 대신 시작 시 종료됩니다. 해당 자격 증명은 ANTHROPIC_API_KEY 또는 ANTHROPIC_AUTH_TOKEN 변수, apiKeyHelper 설정, 또는 이전 Claude Console 로그인으로 저장된 API 키일 수 있습니다.
시작 메시지에는 세션에 구성된 자격 증명, 설정된 위치, 이를 제거하는 단계가 표시됩니다. 예를 들어 셸에 ANTHROPIC_API_KEY 변수가 설정되어 있으면 다음과 같이 표시됩니다:
Not signed in to the Cloud gateway의 경우/login을 실행하고 Cloud gateway 화면에서 로그인을 완료합니다- 시작 메시지의 경우 메시지 끝의 단계에 따라 자격 증명을 제거합니다
- 머신에 게이트웨이가 필요하지 않다고 생각되면 머신을 관리하는 관리자에게 관리형 설정에서
forceLoginMethod와forceLoginGatewayUrl을 제거해 달라고 요청합니다
Administrator policy requires a Cloud gateway sign-in on this machine; the Anthropic-issued credential configured here (ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, or apiKeyHelper) is not used.로 시작했습니다. 이 문구가 표시되고 어떤 자격 증명을 제거해야 할지 알 수 없다면 v2.1.284 이상으로 업데이트하고 claude를 다시 시작합니다.
v2.1.265에서는 회귀 버그로 인해 머신에 관리자 요구 사항이 없는데도 API 키, apiKeyHelper 또는 사용자 지정 헤더로 인증하는 일부 LLM 게이트웨이 및 프록시 구성에서 첫 번째 메시지가 표시되기도 했습니다. v2.1.266 이상으로 업데이트합니다. 구성을 변경할 필요는 없습니다.
v2.1.261 이전에는 forceLoginMethod를 "gateway"로 설정한 머신에서 Claude Code가 모델 요청을 실패시키는 대신 남아 있던 저장된 로그인을 사용했으며, 구성된 환경 자격 증명을 시작 메시지 대신 This machine's managed settings require a first-party login으로 보고했습니다.
Your account is on hold
로그인에 연결된 Claude 계정이 정지되었습니다. Claude Code는 저장된 로그인을 갱신하려다 보류 상태를 알게 되면 첫 번째 메시지를, 브라우저에서 완료한 로그인이 이를 보고하면 두 번째 메시지를 표시합니다:-p)와 Agent SDK에서 구조화된 오류 코드는 account_on_hold입니다. v2.1.235 이전에는 Claude Code가 보류된 계정을 Login expired · Please run /login으로 보고했으며, 해당 복구 단계로는 보류를 해제할 수 없습니다.
해결 방법:
- 메시지의 링크를 열어 보류의 세부 정보를 확인하거나 이의를 제기합니다
- 보류의 영향을 받지 않는 다른 Claude 계정이나 API 키가 있으면 보류가 해결되는 동안 계속 작업할 수 있습니다. 해당 계정으로
/login을 실행하거나ANTHROPIC_API_KEY로 키를 설정합니다
Anthropic profile login expired
Claude Code가 Anthropic 자격 증명 프로필을 통해 인증하고 있는데, 프로필에 저장된 로그인 자격 증명이 만료되었고 프로필에 Claude Code가 이를 갱신하는 데 사용할 수 있는 갱신 자격 증명이 없습니다. Claude Code는 재시도 없이 각 요청을 로컬에서 중단합니다.- 메시지가
Login expired로 시작하면/login을 실행하여 다시 로그인합니다 - 키 없는 Console 로그인 또는 Claude Platform CLI의
ant auth login이 작성한 프로필을 갱신하려면, 키 없는 로그인을 제공하는 머신에서/login을 실행합니다. Anthropic Console 계정을 선택한 다음 Sign in with your Console account를 선택합니다. Claude Code가 해당 프로필의 만료된 자격 증명을 교체합니다 - 다른 도구가 만든 프로필을 갱신하려면 해당 도구로 다시 로그인합니다. 대신
/login에서 Sign in with your Console account를 선택하면, Claude Code는 프로필을 그대로 두고 API 키를 생성합니다 - 관리자가 프로필의 자격 증명을 프로비저닝한 경우 관리자에게 새 자격 증명을 발급해 달라고 요청합니다
/status를 실행하여 활성 자격 증명 소스와 프로필 이름을 확인합니다- 프로필 사용을 중단하려면,
ANTHROPIC_PROFILE을 설정한 경우 설정을 해제한 후/login이나ANTHROPIC_API_KEY같은 다른 방법으로 인증합니다
- Claude Code가 구성 디렉터리에서 프로필을 발견했고 프로필의 인증 모드가
user_oauth인 경우, 메시지는Login expired로 시작하며/login을 먼저 제안합니다. Claude Code는 작동하는/login을 발견된 프로필보다 우선 적용하여 대신 claude.ai 계정으로 인증합니다. v2.1.234부터 v2.1.277까지는 이 형태가Anthropic profile login expired · Run /login to use your claude.ai account instead, or re-authenticate the profile로 표시되었습니다. v2.1.234 이전에는 이 경우에도 Claude Code가Re-authenticate your Anthropic profile형태를 표시했습니다. ANTHROPIC_PROFILE로 프로필을 선택한 경우 메시지는Anthropic profile login expired로 시작합니다.
ANTHROPIC_PROFILE 환경 변수로 선택한 프로필, Claude Code가 Anthropic 구성 디렉터리에서 활성 프로필로 발견한 프로필, 또는 API 키 없이 로그인할 때 Claude Code가 작성한 프로필입니다. API 키, ANTHROPIC_AUTH_TOKEN 같은 bearer 토큰, 또는 서드파티 공급자로 인증하는 세션에서는 이 메시지가 표시되지 않습니다.
OAuth 범위 요구 사항
저장된 토큰이 최신 기능에 필요한 권한 범위보다 이전에 발급되었습니다:/login을 실행하여 현재 범위가 포함된 새 토큰을 받습니다. 먼저 로그아웃할 필요는 없습니다.
claude.ai rejected the session token
claude.ai가 Claude Code 로그인의 토큰을 거부하여 claude.ai 커넥터 요청이 실패했습니다. 거부된 토큰은 claude.ai에서의 커넥터 자체 인가가 아니라 사용자의 로그인이므로, 커넥터를 다시 인가해도 해결되지 않습니다./mcp에서 커넥터는 session token rejected로 표시되며 세부 정보 보기에는 다음이 표시됩니다:
/login을 실행하여 다시 로그인합니다/mcp에서 커넥터를 다시 연결하거나/mcp reconnect <server>를 실행합니다. 다시 로그인하기 전에 다시 연결하면 커넥터가 같은 상태로 남습니다./mcp패널의 Reconnect 옵션은your claude.ai session token was rejected를 보고하지만, 직접 입력하는/mcp reconnect <server>형태는 토큰이 여전히 거부된 상태인데도 다시 연결에 성공했다고 보고합니다.
MCP server needs you to sign in again
원격 MCP 서버가 세션 도중 도구 호출에서 자격 증명을 거부했습니다. 일반적으로 로그인이나 토큰이 만료되었거나, 토큰에 도구에 필요한 권한이 없기 때문입니다. 도구 호출이 실패하고/mcp에서 서버가 인증 필요 상태로 표시됩니다.
claude.ai 커넥터를 포함하여 Claude Code에서 로그인하는 서버의 경우, 로그인이 만료되었거나 취소되었습니다:
/mcp를 실행하고 서버를 선택한 후 메뉴에서 다시 로그인합니다.
headersHelper 스크립트로 구성된 서버의 경우, Claude Code는 이 메시지를 표시하기 전에 이미 헬퍼를 다시 실행하고 호출을 한 번 재시도했습니다:
/mcp에서 다시 연결합니다.
구성에 정적 Authorization 헤더가 있는 서버의 경우:
/mcp에서 다시 연결합니다.
Claude Desktop 앱에서 사용자 머신의 Cowork 세션인 경우, 다음 메시지는 MCP 서버가 제공받은 자격 증명을 거부했다는 뜻입니다. 메시지에 표시된 자격 증명을 수정한 후 Cowork에서 새 작업이나 채팅을 시작합니다:
headersHelper자격 증명 거부: 헬퍼가 서버에서 허용하는 자격 증명을 반환하는지 확인한 후 Cowork에서 새 작업이나 채팅을 시작합니다Authorization헤더 거부: 해당 서버 구성의headers아래Authorization값을 업데이트한 후 Cowork에서 새 작업이나 채팅을 시작합니다
/mcp를 사용할 수 없는데도 Cowork 세션에 run /mcp to reconnect 끝맺음이 대신 표시되었습니다. Cowork에서 이런 끝맺음이 표시되더라도 헬퍼를 확인하거나 헤더를 업데이트한 후 새 작업이나 채팅을 시작합니다. v2.1.273 이전에는 로그인 만료, headersHelper, Authorization 헤더 경우 모두 MCP server "<name>" requires re-authorization (token expired)가 표시되었습니다.
서버는 HTTP 403 insufficient_scope로 도구 호출을 거부하여 범위 인가를 요청할 수도 있으며, 때로는 토큰에 이미 나열된 범위를 요청하기도 합니다. 메시지에 해당 범위가 표시됩니다:
/mcp를 실행하고 서버를 선택한 후 메뉴에서 다시 인증합니다.
서버 구성에 oauth.scopes와 authServerMetadataUrl이 모두 설정되어 있지 않으면 Claude Code는 서버가 지정한 범위를 요청합니다. 둘 중 하나라도 설정되어 있으면 Claude Code는 대신 해당 설정의 범위를 요청합니다. oauth.scopes를 고정했다면 다시 인증하기 전에 누락된 범위를 해당 목록에 추가합니다.
v2.1.274 이전에는 이 경우 needs you to sign in again 메시지가 표시되었고, v2.1.273 이전에는 다른 경우와 마찬가지로 requires re-authorization (token expired)가 표시되었습니다.
Couldn’t read the stored credentials for MCP server
Claude Code는 OAuth MCP 서버의 로그인 정보를 자격 증명 저장소에 보관합니다. 이 메시지는 Claude Code가 해당 저장소를 읽을 수 없어 서버에 대한 요청이 실행되지 않았다는 뜻입니다:claude -p 또는 Agent SDK 실행에서는 저장된 로그인 정보 없이 요청이 이미 전송된 후에 키체인을 읽을 수 있게 될 수 있습니다. 해당 요청은 다음과 같이 실패합니다:
-
메시지가 Mac 키체인 잠금 해제를 요청하면, Claude Code를 실행하는 셸 세션에서
claude doctor를 실행하고 보고서에 키체인 경고가 있는지 확인합니다:-
보고서에
macOS Keychain is not writable로 시작하는 경고가 있거나 셸에claude명령이 없으면, 해당 셸 세션에서 다음 잠금 해제 명령을 실행합니다: - 보고서에 키체인 경고가 없으면 잠금 해제 명령을 건너뜁니다
-
보고서에
-
메시지가 표시된 곳에서 다시 시도합니다:
claude -p의 경우 명령을 다시 실행합니다- 대화형 세션에서는
/mcp에서 서버가 실패로 표시되면 다시 연결한 후 Claude에게 다시 시도하도록 요청합니다 - 계속 실행 중인 Agent SDK 애플리케이션에서는 TypeScript의
reconnectMcpServer()또는 Python의ClaudeSDKClient.reconnect_mcp_server()를 호출하거나 새 세션을 시작합니다
-
그 후 서버가 인증이 필요하다고 보고하면, Claude Code가 해당 서버에 사용할 수 있는 로그인을 찾지 못한 것입니다. 대화형으로 로그인합니다. Claude Code 세션에서
/mcp를 실행하거나 셸에서claude mcp login <name>을 실행합니다. Agent SDK 애플리케이션에서는 Agent SDK의 OAuth2 인증을 참조합니다.
claude -p 또는 Agent SDK를 실행하면 두 메시지 중 어느 것도 표시하지 않고 서버를 인증이 필요한 것으로 보고했습니다.
MCP server URL is missing or not a valid URL
서버에 구성된url을 URL로 파싱할 수 없어 Claude Code가 원격 MCP 서버의 OAuth 로그인 시작을 거부했습니다. Claude Code가 해당 서버에 대해 보고할 더 구체적인 구성 문제가 있는 경우를 제외하고, 셸에서 claude mcp login <name>을 실행하면 다음과 같이 거부 메시지가 출력됩니다.
- 서버가 구성된 위치에서 해당 항목의
url을 서버의 실제 엔드포인트로 설정하거나, 해당 항목의${VAR}참조가 가리키는 환경 변수를 설정한 다음 로그인을 다시 실행합니다.
Issuer mismatch in authorization response
MCP OAuth 로그인 중에 인가 서버가 Claude Code로 다시 리디렉션하면서 보낸iss 매개변수가 Claude Code가 서버의 OAuth 메타데이터에서 기대한 발급자(issuer)를 가리키지 않습니다. 이 단계에서 잘못된 발급자가 나타나는 것은 인가 서버 혼동(mix-up) 공격의 전형적인 모습이므로, Claude Code는 인가 코드를 교환하는 대신 로그인을 실패 처리합니다. Claude Code는 브라우저 로그인 후 /mcp 서버 메뉴에 다음 오류를 표시합니다.
expected는 서버의 OAuth 메타데이터에 있는 발급자이고, received는 리디렉션에 포함된 iss 값입니다. 리디렉션에 iss 매개변수가 없는 로그인은 검사를 통과합니다. 단, 서버의 메타데이터가 authorization_response_iss_parameter_supported를 설정한 경우에는 Claude Code가 로그인을 실패 처리합니다.
해결 방법:
/mcp에서 로그인을 다시 시도합니다- 오류가 반복되면 서버 운영자에게 보고합니다. 해결은 서버 측에서 이루어져야 합니다. 인가 서버는 메타데이터에 알리는 것과 동일한 발급자를
iss매개변수로 반환해야 합니다 - 서버가 수정되는 동안 연결하려면
MCP_SDK_GENERATION=v1로 Claude Code를 시작합니다. 이 런타임은 이 검사를 실행하지 않습니다. 이렇게 하면 혼동 공격에 대한 보호 기능이 제거되므로 서버 측 수정을 우선하는 것이 좋습니다
MCP_SDK_GENERATION=v2를 설정한 경우에만 v2 런타임을 사용했습니다.
Stopped an OAuth request
이 메시지는 OAuth 엔드포인트가 리디렉션했기 때문에 Claude Code가 MCP 서버에 대한 OAuth 요청을 중단했음을 의미합니다. 두 가지 형태의 메시지 모두에서 첫 번째 주소가 리디렉션을 보낸 주소입니다.- MCP 서버 운영자 등 첫 번째 주소를 운영하는 사람에게 리디렉션을 제거하거나 수정하도록 요청합니다. 그런 다음
/mcp에서 다시 시도합니다.
Refusing to send credentials to non-https token endpoint
v2 런타임에서 Claude Code는 HTTPS로 제공되거나localhost, 127.0.0.1, ::1에 있는 토큰 엔드포인트에만 MCP OAuth 토큰 요청을 보냅니다. 이 메시지는 서버의 토큰 엔드포인트가 둘 중 어디에도 해당하지 않아 Claude Code가 요청을 보내기 전에 중단했음을 의미합니다. 이는 브라우저 로그인 이후에 발생하므로 브라우저 단계는 먼저 성공하며, Claude Code가 서버의 토큰을 갱신할 때마다 다시 발생합니다.
전체 형태의 메시지는 MCP SDK에서 생성되며 거부된 토큰 엔드포인트를 인용합니다. 디버그 로그에서는 로그인의 경우 Error during auth completion: 뒤에, 갱신의 경우 Token refresh failed: 뒤에 나타납니다. 셸에서는 claude mcp login <name>이 Couldn't complete authentication for "<name>": 뒤에 이 메시지를 출력하며, 세션에서는 /mcp가 서버 메뉴 아래에 표시합니다.
io처럼 릴리스마다 바뀔 수 있는 짧은 이름 뒤에 from the MCP SDK for와 수정된 서버 URL이 붙은 형태로 표시됩니다. MCP SDK의 다른 오류도 그곳에서 같은 형태를 띱니다. 수정된 메시지가 이 오류일 수 있는 경우는 서버의 토큰 엔드포인트가 localhost, 127.0.0.1, ::1 이외의 주소에 있는 일반 http://인 경우뿐입니다.
해결 방법:
- 해당 토큰 엔드포인트를 HTTPS로 제공합니다. 예를 들어 TLS를 종료하는 리버스 프록시나 터널 뒤에 서버를 두고, 서버가
https://주소를 알리도록 구성합니다 - 서버를 변경하지 않고 연결하려면
MCP_SDK_GENERATION=v1로 Claude Code를 시작합니다. 이 런타임은 이 규칙을 적용하지 않으며 일반 HTTP로 토큰 요청을 보냅니다. 이 선택은 종료할 때까지 유지되며 모든 서버에 적용됩니다. v1 런타임은 발급자 검사도 건너뛰므로 엔드포인트를 HTTPS로 제공하는 방법을 우선하는 것이 좋습니다
AWS credentials expired or invalid
AWS 세션 토큰이 만료되었거나 거부되었습니다. 이 메시지는 Claude Platform on AWS 또는 Mantle 엔드포인트에서 401이 반환될 때 나타나며, 이는 해당 제공자들이 만료된 보안 토큰을 보고하는 방식입니다. 중간의 작업 힌트는 설정에 따라 달라집니다. 변하지 않는 부분은 앞쪽의AWS credentials expired or invalid입니다.
awsAuthRefresh가 구성된 경우에만 이 메시지가 나타났습니다.
해결 방법:
- 힌트에 자격 증명이 이 환경에서 관리된다고 표시되면 Claude Code를 실행한 앱이 자격 증명을 소유하므로 여기의 다른 단계는 적용되지 않습니다. 재시도하거나 관리자에게 문의합니다
awsAuthRefresh가 설정되어 있으면 메시지에 표시된aws sso login --profile myprofile같은 명령을 다른 터미널에서 실행하고 브라우저 로그인을 완료한 다음 재시도합니다. 그렇지 않으면 사용 중인 AWS 자격 증명(SSO 로그인, 액세스 키, API 키 또는 프록시 토큰)을 직접 갱신합니다- 대화형 세션에서
awsAuthRefresh가 설정되어 있으면 대신/login을 실행하고 3rd-party platform을 선택한 다음 Using 3rd-party platforms 아래에서 Claude Platform on AWS · refresh credentials를 선택하여 Claude Code를 다시 시작하지 않고 같은 명령을 실행할 수 있습니다. AWS 자격 증명 구성을 참조하세요 - 갱신 명령이 성공한 후에도 오류가 반복되면 같은 셸과 프로필에서
aws sts get-caller-identity를 실행하여 Claude Code 외부에서 해당 ID가 유효한지 확인합니다
AWS authentication failed
AWS 제공자가 403을 반환했거나 Amazon Bedrock이 401을 반환했습니다. Amazon Bedrock은 만료된 보안 토큰을 403으로 보고하지만, 누락된 IAM 권한으로 인한AccessDeniedException과 같은 인가 거부도 403으로 보고합니다. Claude Code는 이 두 가지 원인을 구분할 수 없습니다.
Amazon Bedrock의 401도 AWS credentials expired or invalid가 아닌 여기에 해당합니다. Amazon Bedrock은 만료된 토큰을 401로 보고하지 않기 때문입니다. 해당 엔드포인트의 401은 일반적으로 회사 프록시와 같이 요청 경로의 다른 요소에서 발생합니다.
자격 증명 갱신은 만료된 토큰은 해결하지만 다른 원인은 해결할 수 없으므로, 메시지는 두 가지를 모두 제시합니다.
AWS authentication failed입니다.
403이 지정된 모델 ID의 모델에 대한 액세스 권한이 없다는 Amazon Bedrock의 응답인 경우, 힌트는 대신 Amazon Bedrock 콘솔에서 계정과 리전에 대해 해당 모델을 활성화하도록 안내합니다.
v2.1.273 이전에는 awsAuthRefresh가 구성된 경우에만 이 메시지가 나타났습니다.
해결 방법:
- 힌트에 자격 증명이 이 환경에서 관리된다고 표시되면 Claude Code를 실행한 앱이 자격 증명을 소유하므로 여기의 다른 단계는 적용되지 않습니다. 재시도하거나 관리자에게 문의합니다
- 만료된 자격 증명이 원인일 경우에 대비해 AWS 자격 증명을 갱신합니다.
awsAuthRefresh가 설정되어 있으면 메시지에 표시된 명령을 실행하고, 그렇지 않으면 SSO 로그인, 액세스 키, API 키 또는 프록시 토큰을 직접 갱신합니다 - 자격 증명이 최신 상태라면 IAM 구성의 IAM 권한이 사용 중인 ID에 연결되어 있는지, 선택한 모델이 계정과 리전에 대해 활성화되어 있는지 확인합니다
aws sts get-caller-identity를 실행하여 요청에 사용되는 ID를 확인합니다
Google Cloud credentials expired or invalid
Google Cloud의 Agent Platform용 Google Cloud 자격 증명이 만료되었거나 거부되었습니다. 요청이 401을 반환했으며, 이는 Agent Platform이 자격 증명 만료를 보고하는 방식입니다. 중간의 작업 힌트는 설정에 따라 달라집니다. 변하지 않는 부분은 앞쪽의Google Cloud credentials expired or invalid입니다.
- 힌트에 자격 증명이 이 환경에서 관리된다고 표시되면 Claude Code를 실행한 앱이 자격 증명을 소유하므로 여기의 다른 단계는 적용되지 않습니다. 재시도하거나 관리자에게 문의합니다
CLAUDE_CODE_USE_ANTHROPIC_GOOGLE_CLOUD를 설정했다면 대신 Claude Models on Google Cloud (Anthropic managed)의 단계를 따릅니다- 애플리케이션 기본 자격 증명으로 인증하는 경우 메시지에 표시된
gcpAuthRefresh명령 또는gcloud auth application-default login을 실행하고 로그인을 완료한 다음 재시도합니다 CLAUDE_CODE_SKIP_VERTEX_AUTH를 설정하고 LLM 게이트웨이를 통해 라우팅하는 경우ANTHROPIC_AUTH_TOKEN또는ANTHROPIC_CUSTOM_HEADERS의 게이트웨이 토큰을 갱신한 다음 재시도합니다- 서비스 계정 키 파일로 인증하는 경우
GOOGLE_APPLICATION_CREDENTIALS가 유효한 키를 가리키는지 확인합니다. GCP 자격 증명 구성을 참조하세요 - 갱신 후에도 오류가 반복되면 같은 셸에서
gcloud auth application-default print-access-token을 실행하여 Claude Code 외부에서 해당 ID가 작동하는지 확인합니다
Please run /login 또는 Failed to authenticate 메시지가 대신 표시되었으며, 이 방법으로는 Google Cloud 자격 증명을 갱신할 수 없습니다.
Google Cloud authentication failed
Google Cloud의 Agent Platform이 403을 반환했습니다. Agent Platform은 만료된 자격 증명이 아닌 인가 거부에 403을 사용합니다. 일반적으로 인증에 사용하는 ID에 IAM 권한이 없거나 프로젝트에 대해 모델이 활성화되어 있지 않은 경우입니다. 중간의 작업 힌트는 설정에 따라 달라집니다. 변하지 않는 부분은 앞쪽의Google Cloud authentication failed입니다.
- 힌트에 자격 증명이 이 환경에서 관리된다고 표시되면 Claude Code를 실행한 앱이 자격 증명을 소유하므로 여기의 다른 단계는 적용되지 않습니다. 재시도하거나 관리자에게 문의합니다
CLAUDE_CODE_USE_ANTHROPIC_GOOGLE_CLOUD를 설정했다면 대신 Claude Models on Google Cloud (Anthropic managed)의 단계를 따릅니다- IAM 구성의 역할이 인증에 사용하는 ID에 부여되어 있는지 확인합니다
- 프로젝트에 대해 모델이 활성화되어 있는지 확인합니다. 모델 액세스 요청을 참조하세요
Please run /login 또는 Failed to authenticate 메시지가 대신 표시되었으며, 이 방법으로는 Google Cloud 자격 증명을 갱신할 수 없습니다.
Microsoft Foundry authentication failed
Microsoft Foundry가 401 또는 403을 반환했습니다. 요청의 Azure 자격 증명이 거부되었거나, 그 뒤의 ID에 Foundry 리소스에 대한 액세스 권한이 없습니다./login은 Azure 자격 증명을 발급할 수 없습니다. 중간의 작업 힌트는 설정에 따라 달라집니다. 변하지 않는 부분은 앞쪽의 Microsoft Foundry authentication failed입니다.
- 힌트에 자격 증명이 이 환경에서 관리된다고 표시되면 Claude Code를 실행한 앱이 자격 증명을 소유하므로 여기의 다른 단계는 적용되지 않습니다. 재시도하거나 관리자에게 문의합니다
- Azure 자격 증명 구성에서 구성한 자격 증명을 갱신합니다.
ANTHROPIC_FOUNDRY_API_KEY를 교체하거나, 새ANTHROPIC_FOUNDRY_AUTH_TOKEN을 발급하거나, 기본 Microsoft Entra 자격 증명 체인이 다시 로그인할 수 있도록az login을 실행합니다 - 자격 증명이 최신 상태라면 해당 ID에 Foundry 리소스에 대한 액세스 권한이 있는지 확인합니다. Azure RBAC 구성을 참조하세요
Please run /login 또는 Failed to authenticate 메시지가 대신 표시되었으며, 이 방법으로는 Azure 자격 증명을 갱신할 수 없습니다.
Could not load AWS or Google Cloud credentials
Claude Code가 실행 중인 머신에서 AWS 자격 증명 제공자 체인이나 Google 애플리케이션 기본 자격 증명으로부터 사용 가능한 자격 증명을 얻지 못해, 어떤 요청도 클라우드 제공자에 도달하지 않았습니다.· 뒤의 세부 정보는 만료된 SSO 세션, Could not load the default credentials로 보고되는 애플리케이션 기본 자격 증명 누락, invalid_grant로 보고되는 취소된 로그인 등 구체적인 원인을 나타냅니다.
-p를 사용하는 비대화형 모드와 Agent SDK에서 구조화된 오류 코드는 cloud_credential_error입니다. v2.1.267 이전에는 메시지에 API Error: 뒤의 세부 텍스트만 표시되었고, 구조화된 코드는 server_error 또는 unknown이었습니다.
해결 방법:
aws sso login --profile myprofile또는gcloud auth application-default login과 같은 제공자의 로그인 명령을 실행한 다음 재시도합니다. Bedrock, Agent Platform 또는 Foundry 자격 증명이 로드되지 않음에서 Claude Code 외부에서 자격 증명을 확인하는 방법을 설명합니다- 세부 정보가
AWS default-chain credential resolve timed out이라면 체인이 실패한 것이 아니라 멈춘 것이므로 대신 AWS default-chain credential resolve timed out을 따릅니다
AWS default-chain credential resolve timed out
AWS 기본 자격 증명 제공자 체인이 60초 이내에 자격 증명을 생성하지 못해 Claude Code가 확인 작업을 중단하고 요청을 실패 처리했습니다. 이 타임아웃은 Could not load AWS or Google Cloud credentials의 원인 중 하나입니다. 이 실패는 로컬 자격 증명 확인 단계에서 발생한 것으로, 요청은 Amazon Bedrock, Claude Platform on AWS 또는 Mantle 엔드포인트에 도달하지 않았습니다. Claude Code는 이 오류를 표시하기 전에 자격 증명 캐시를 지우고 재시도하므로, 이 오류가 보일 때는 체인이 반복된 시도에서 멈춘 상태입니다.credential_process 명령이 받을 수 없는 입력을 기다리는 경우, 그리고 컨테이너나 VM의 인스턴스 메타데이터 서비스(IMDS)가 체인의 프로브에 응답하지 않는 경우입니다.
v2.1.267 이전에는 메시지가 API Error: AWS default-chain credential resolve timed out이었습니다.
v2.1.207 이전에는 체인이 멈추면 요청이 실패하지 않고 무기한 대기했습니다.
해결 방법:
- 같은 셸에서 같은
AWS_PROFILE로aws sts get-caller-identity를 실행합니다. 이 명령도 멈춘다면 프로필을 수정합니다. 대화형으로 입력을 요청하는credential_process명령이 흔한 원인입니다. - Claude Code를 시작하기 전에 로그인 단계를 완료합니다. 예:
aws sso login --profile myprofile aws-vault같은 래퍼를 통한 MFA 포함 SSO처럼 체인이 실제로 60초 이상 필요한 대화형 로그인을 실행하는 경우CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS로 제한을 밀리초 단위로 늘립니다
Bedrock 설정 확인이 AWS를 기다리다 시간 초과됨
Bedrock 설정 마법사의 자격 증명 확인 중에 자격 증명 조회나 ID 확인 같은 AWS 호출이 60초 제한 내에 완료되지 않았습니다. 마법사는 대기를 중단하고 확인 단계를 실패 처리합니다.CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS에 설정한 값이 있으면 그 값입니다.
일반적인 원인은 SSO 토큰 갱신을 포함해 AWS로의 요청을 지연시키는 네트워크나 프록시, 그리고 화면에 보이지 않는 입력을 계속 기다리는 자격 증명 헬퍼입니다. 헬퍼가 실제로 더 많은 시간이 필요한 경우에만 제한을 늘립니다.
AWS로의 단일 요청이 멈춘 경우 자체 요청별 타임아웃으로 실패할 수도 있으며, 이때는 같은 단계에서 더 짧은 메시지가 표시됩니다.
unreachable로 표시합니다.
해결 방법:
- 같은 셸에서
aws sts get-caller-identity를 실행합니다. 이 명령도 멈춘다면 지연은 Claude Code 외부, 즉 네트워크, 프록시 또는 AWS 프로필의 자격 증명 헬퍼에서 발생하는 것이므로 먼저 이를 해결합니다. - 마법사를 열기 전에 대화형 로그인을 완료합니다. 예:
aws sso login --profile myprofile - AWS 프로필의 자격 증명 헬퍼가 입력을 요청하는 데 실제로 60초보다 오래 걸리는 경우
CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS로 제한을 밀리초 단위로 늘립니다
Cloud gateway session expired
Claude apps gateway를 통해 로그인했으며, 이 머신에 저장된 게이트웨이 세션이 만료되어 갱신할 수 없거나, 게이트웨이의 JWT 시크릿이 교체된 후처럼 게이트웨이가 더 이상 해당 세션을 허용하지 않습니다.claude를 대화형으로 시작할 때 이 줄이 보이면 세션이 게이트웨이에서 로그아웃된 상태로 열린 것입니다.
claude auth 이외의 claude 하위 명령에서는 게이트웨이가 더 이상 세션을 허용하지 않을 때 Claude Code가 대신 다음 메시지와 함께 종료됩니다.
- 세션에서
/login을 실행하고 브라우저 로그인을 완료합니다 - 비대화형 실행의 경우 같은 환경에서
claude를 시작하고/login을 실행한 다음 명령을 다시 실행합니다
Sign-in timed out while waiting for you to continue
Claude apps gateway 로그인 중에 게이트웨이가 로그인한 계정을 알려 주었고, Claude Code는 자격 증명을 저장하기 전에 이를 확인하도록 요청했습니다. 확인 화면이 로그인 자체의 만료 시간을 넘겨 열려 있었고, 게이트웨이가 이를 갱신할 수 있는 리프레시 토큰을 발급하지 않았기 때문에 계속 진행했을 때 Claude Code는 아무것도 저장하지 않았습니다./login을 다시 실행하고 로그인이 만료되기 전에 계정을 확인합니다
Gateway refused the request
Claude apps gateway를 통해 로그인한 상태에서 요청이 403을 반환했습니다. 게이트웨이 또는 그 뒤의 업스트림이 요청을 거부한 것입니다. 다시 로그인해도 거부는 바뀌지 않으므로 메시지는 게이트웨이 관리자에게 문의하도록 안내합니다.- 게이트웨이 관리자에게 해당 요청을 조회해 달라고 요청합니다.
API Error:뒷부분에 게이트웨이가 반환한 거부 내용이 담겨 있습니다 - 관리자의 경우: 게이트웨이의 액세스 제어 규칙은 403을 반환하며 감사 로그에 그 사유가 기록됩니다. 업스트림의 인가 거부는 업스트림 오류 메시지에 따라 그대로 전달됩니다
Please run /login 또는 Failed to authenticate 메시지가 대신 표시되었으며, 다시 로그인해도 거부가 해소되지 않았습니다.
네트워크 및 연결 오류
이러한 오류의 대부분은 Claude Code의 네트워크 요청이 목적지에 도달하지 못했거나, Claude Code와 API 사이에 있는 무언가가 돌아오는 응답을 변경했음을 의미합니다. 아카이브 쓰기 실패처럼 로컬 원인도 있는 항목은 본문에 그 내용이 명시되어 있습니다. 이러한 오류는 보통 로컬 네트워크, 프록시, 방화벽 또는 클라우드 환경의 네트워크 정책에서 발생합니다.Unable to connect to API
API에 대한 TCP 연결이 실패했거나 완료되지 않았습니다. 일반적인 연결 오류 코드의 경우 메시지에 실패 유형이 표시되고 코드는 괄호 안에 유지됩니다.Unable to connect to API 뒤에 괄호로 코드가 붙은 형태로 표시됩니다. 일부 메시지는 둘 이상의 코드를 표시할 수 있습니다. 예를 들어 Connection refused는 ConnectionRefused 또는 ECONNREFUSED를, Can't reach the API server는 ENOTFOUND 또는 FailedToOpenSocket을 표시할 수 있습니다.
v2.1.227 이전에는 이러한 코드가 포함된 메시지가 모두 Unable to connect to API (ECONNREFUSED)처럼 Unable to connect to API 뒤에 코드가 붙은 형태였습니다.
일반적인 원인으로는 인터넷 접속 불가, api.anthropic.com을 차단하는 VPN, 필수 회사 프록시가 구성되지 않은 경우 등이 있습니다.
해결 방법:
- 같은 셸에서
curl -I https://api.anthropic.com을 실행하여 API 호스트에 접근할 수 있는지 확인합니다. Windows PowerShell에서는 기본 제공Invoke-WebRequest별칭이 사용되지 않도록curl.exe -I https://api.anthropic.com을 사용합니다. - 회사 프록시 뒤에 있다면 Claude Code를 실행하기 전에
HTTPS_PROXY를 설정하고 네트워크 구성을 참조합니다 - LLM 게이트웨이나 릴레이를 경유한다면
ANTHROPIC_BASE_URL을 해당 주소로 설정합니다. 설정 방법은 Claude Code를 LLM 게이트웨이에 연결하기를 참조합니다. ANTHROPIC_BASE_URL이 이미 게이트웨이를 가리키고 있는데 모든 요청이Connection dropped로 끝난다면, 게이트웨이와 그 업스트림이 도구 검색 필드를 허용하는지 확인합니다. 기본적으로 Claude Code는defer_loading도구 필드와tool_reference블록을 이를 활성화하는anthropic-beta헤더와 함께 전송합니다. v2.1.304 이전에는ENABLE_TOOL_SEARCH로 직접 켠 경우를 제외하고 게이트웨이 뒤에서는 도구 검색이 꺼져 있었습니다.- 방화벽이 네트워크 액세스 요구 사항에 나열된 호스트를 허용하는지 확인합니다
- 간헐적인 실패는 자동으로 재시도됩니다
curl은 성공하지만 Claude Code가 여전히 실패한다면, 원인은 대개 네트워크 자체가 아니라 런타임과 네트워크 사이의 무언가입니다.
echo $ANTHROPIC_BASE_URL(PowerShell에서는echo $env:ANTHROPIC_BASE_URL)을 실행하여ANTHROPIC_BASE_URL이 설정되어 있는지 확인하고, 설정 파일의env블록에도 있는지 살펴봅니다. 이 값이 설정되어 있으면 Claude Code는 모델 요청을api.anthropic.com대신 해당 주소로 보내므로, 더 이상 실행되지 않는 로컬 프록시나 게이트웨이를 가리키는 값이 남아 있으면curl이 API에 도달하더라도Connection refused가 발생합니다. 셸 프로필이나 설정에서 이 값을 제거하고 새 터미널에서 Claude Code를 시작합니다.- Linux와 WSL에서는
/etc/resolv.conf에 접근할 수 없는 네임서버가 있는지 확인합니다. 특히 WSL은 호스트로부터 잘못된 리졸버를 상속받을 수 있습니다. - macOS에서는 연결이 끊기거나 제거된 VPN 클라이언트가 터널 인터페이스나 라우팅 규칙을 남길 수 있습니다.
ifconfig에서 오래된utun인터페이스가 있는지 확인하고 시스템 설정에서 VPN의 네트워크 확장을 제거합니다. - Docker Desktop 및 유사한 컨테이너 런타임은 아웃바운드 트래픽을 가로챌 수 있습니다. 이를 배제하려면 해당 프로그램을 종료하고 다시 시도합니다.
Unable to connect to Anthropic services
최초 실행 설정 중에 Claude Code는 로그인 단계를 표시하기 전에api.anthropic.com과 platform.claude.com에 접근할 수 있는지 확인합니다. 둘 중 하나의 확인이 실패하면 Claude Code는 이유를 출력하고 종료합니다.
HTTPS_PROXY처럼 해당 프록시를 구성한 환경 변수의 이름이 표시됩니다. v2.1.222 이전에는 이 확인이 타임아웃이 없는 다른 프록시 전송 방식을 사용했습니다. 그래서 https:// 스킴을 사용하는 프록시 URL 뒤에서는 Checking connectivity... 상태에서 무기한 멈춘 뒤, 같은 프록시를 통한 API 요청은 성공하는데도 실패할 수 있었습니다.
관리형 설정 파일, MDM 정책 또는 정책 헬퍼가 forceLoginMethod를 "gateway"로 설정하거나, forceLoginMethod 없이 forceLoginGatewayUrl을 설정한 경우 Claude Code는 이 확인을 건너뜁니다. 두 구성 모두에서 Claude Code는 Anthropic 로그인 방식 대신 Cloud gateway 화면에서 로그인 단계를 엽니다. 또한 머신에 관리형 설정 소스가 존재하지만 읽을 수 없는 경우에도, 해당 소스에 게이트웨이 구성이 있을 수 있으므로 Claude Code는 확인을 건너뜁니다. v2.1.247 이전에는 이 구성에서도 Claude Code가 확인을 실행했으며, Anthropic의 엔드포인트에 접근할 수 없으면 이 오류와 함께 종료했습니다.
관리형 설정이 없는 머신에서 사용자 자신의 ~/.claude/settings.json이 forceLoginMethod와 forceLoginGatewayUrl로 게이트웨이를 지정한 경우에도 Claude Code는 확인을 건너뜁니다. v2.1.295 이전에는 이 경우에도 Claude Code가 확인을 실행했습니다.
해결 방법:
- 메시지에 프록시 변수가 표시되면 그 값이 올바른 프록시를 가리키는지 확인하고, 네트워크 팀에 해당 프록시를 통해 메시지에 표시된 호스트로의 HTTPS 연결을 허용해 달라고 요청합니다. 네트워크 구성을 참조합니다.
- Unable to connect to API의 확인 사항을 차례로 점검합니다. 그곳의
curl테스트와 방화벽 안내는 이 확인에도 적용됩니다. - 네트워크가 열려 있는데도 실패가 계속된다면 Claude Code가 해당 국가에서 제공되지 않을 수 있습니다
Socket is closed
Socket is closed는 스트리밍 응답을 전달하던 연결이 응답이 아직 도착하는 중에 닫혔음을 의미합니다. 가장 흔한 원인은 Windows의 회사 프록시가 응답 도중에 이미 설정된 터널을 끊는 것입니다.
응답이 얼마나 진행되었는지에 따라 Claude Code는 요청을 재시도하거나, Claude가 생성한 내용을 유지하거나, 턴을 종료합니다. 자동 재시도를 참조합니다.
v2.1.214 이전에는 Claude Code가 이 실패를 재시도하지 않았으며, 턴이 Socket is closed를 포함한 오류와 함께 중단되었습니다.
해결 방법:
- 이 오류가 표시되면
claude update로 v2.1.214 이상으로 업데이트한 다음 메시지를 다시 보냅니다 - 업데이트 후에도 같은 프록시 뒤에서 턴이 계속 실패한다면 Unable to connect to API의 내용을 점검하고 네트워크 구성에서 프록시 설정을 확인합니다
API returned an empty or malformed response
Claude Code는 실패한 스트리밍 요청을 비스트리밍으로 재시도했을 때 HTTP 성공 상태를 받았지만 본문이 Claude API 메시지가 아닌 경우 이 오류를 표시합니다. 흔히 HTML 오류 페이지나 로그인 페이지, 빈 본문, 또는 다른 형식의 JSON입니다. 보통 프록시, 게이트웨이 또는 네트워크 로그인 페이지가 API 대신 응답한 것이 원인입니다. Claude Code는 요청을 재시도하지 않으며, 턴은 이 오류와 함께 종료됩니다.- 콘텐츠 유형,
body is an HTML page나empty body같은 본문의 종류, 바이트 단위 크기, 응답에 Anthropic 요청 ID가 포함되었는지 여부를 담은Response:절. 응답에nginx나cloudflare처럼 식별 가능한 서버가 명시되어 있거나cf-ray나via같은 중간자 헤더가 포함되어 있으면 이 절에 해당 내용도 나열됩니다. - 실패한 스트리밍 요청의 ID와 재시도를 유발한 실패를 명시하는 문장. 실패 전에 스트림이 열려 있었다면, 도착한 스트림 이벤트 수와, 이벤트가 하나라도 도착했다면 시도가 실패했을 때 스트림이 얼마나 오래 응답이 없었는지도 보고합니다.
intercepting the request 뒤에서 끝났습니다.
v2.1.271 이전에는 text/plain처럼 JSON이 아닌 콘텐츠 유형으로 유효한 API 메시지를 전달한 응답도 이 오류와 함께 턴을 종료했습니다. 일부 LLM 게이트웨이는 비스트리밍 응답에 이 콘텐츠 유형을 사용합니다.
해결 방법:
Response:절을 읽고 어떤 시스템이 응답했는지 확인합니다. HTML 본문, Anthropic 요청 ID 없음, 또는nginx나cloudflare같은 서버 이름은 Claude Code와 API 사이의 무언가가 API 대신 응답했음을 의미합니다- LLM 게이트웨이를 경유한다면 직접 요청으로 경로를 테스트하고 API가 아닌 응답을 반환하는 구간을 수정합니다
- 게스트 Wi-Fi처럼 로그인 페이지가 있는 네트워크에서는 브라우저에서 로그인을 완료한 다음 다시 시도합니다
- 게이트웨이를 통한 비스트리밍 경로만 문제가 있다면
CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1을 설정하여 이 폴백을 끕니다. 단, 스트리밍 엔드포인트 자체가404를 반환하는 경우에는 Claude Code가 여전히 폴백합니다
Streaming response ended before any complete data was received
모델 제공업체의 스트리밍 응답이 사용 가능한 데이터를 전혀 전달하지 않고 완료되었으므로, Claude Code가 턴을 마치기 위해 스트리밍 없이 요청을 다시 보냈습니다. Claude Code는 이 경고를 대화형 세션에서만 세션당 한 번 표시합니다. v2.1.239 이전에는 Claude Code가 경고 없이 스트리밍 없이 재시도했습니다.- Claude Code와 모델 제공업체 사이의 프록시나 게이트웨이가 스트리밍 응답 본문과 헤더를 수정 없이 그대로 전달하도록 구성합니다
- Amazon Bedrock에서는 헤더 및 본문 요구 사항에 대해 게이트웨이 또는 프록시 뒤의 스트리밍 오류를 참조합니다
Bedrock streaming response has an unexpected content-type
Claude Code와 Amazon Bedrock 사이의 게이트웨이나 프록시가 스트리밍 응답 본문이나Content-Type 헤더를 변환하고 있습니다. Amazon Bedrock은 응답을 application/vnd.amazon.eventstream으로 스트리밍합니다. Claude Code는 읽을 수 없는 본문을 디코딩하는 대신, 다른 content-type을 보고하는 성공한 스트리밍 응답을 거부합니다. Claude Code는 요청을 재시도하지 않습니다.
API Error: Truncated event message received로 나타났습니다.
해결 방법:
- 게이트웨이가
InvokeModelWithResponseStream응답 본문과Content-Type헤더를 수정 없이 그대로 전달하도록 구성합니다. 스트림을 server-sent events로 다시 내보내는 중간자가 흔한 원인입니다. CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1을 설정하면 이 오류가 숨겨지지만, Claude Code는 다시 작성된 헤더 아래의 바이너리 본문을 디코딩하지 않으므로 해당 요청은 더 느린 비스트리밍 경로로 폴백합니다. 게이트웨이 또는 프록시 뒤의 스트리밍 오류를 참조합니다.
SSL 인증서 오류
네트워크의 프록시나 보안 장비가 자체 인증서로 TLS 트래픽을 가로채고 있으며, Claude Code가 이 인증서를 신뢰하지 않습니다.NODE_EXTRA_CA_CERTS 힌트 없이 Check your proxy or corporate SSL certificates에서 끝났습니다.
v2.1.199부터는 인증서 검증 실패가 재시도되지 않으므로, 이 오류는 전체 재시도 한도를 소진한 후가 아니라 첫 번째 시도에서 표시됩니다. 이전 버전에서는 오류를 표시하기 전에 몇 분 동안 재시도했습니다. 핸드셰이크 시간 초과 같은 일시적인 TLS 상황은 여전히 재시도됩니다.
/login 및 시작 시 연결 확인 중에는 같은 실패가 다른 메시지를 생성합니다.
- 조직의 CA 번들을 내보내고
NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem으로 Claude Code가 이를 가리키도록 합니다 - 전체 설정 방법은 네트워크 구성을 참조합니다
- 인증서 검증을 완전히 비활성화하는
NODE_TLS_REJECT_UNAUTHORIZED=0은 설정하지 마십시오
클라우드 세션에서 허용되지 않는 호스트
클라우드 세션이나 클라우드 예약 작업에서403 또는 ENOTFOUND 같은 DNS 오류는 요청한 호스트가 클라우드 환경의 허용 목록에 없음을 의미할 수 있습니다. 확인하려면 해당 목록과 호스트를 대조합니다. 다음 헤더가 있는 403은 차단을 확정하지만, 차단된 요청의 403에 모두 이 헤더가 있는 것은 아닙니다.
- GitHub 및 커넥터 트래픽: GitHub 작업과 MCP 커넥터 트래픽은 별도의 채널을 사용하므로, 다른 호스트가 차단되어도 계속 작동할 수 있습니다
- 기본 환경: Default 환경은 Allow package managers가 선택된 Limited 액세스를 사용합니다. 이 환경의 세션은 패키지 레지스트리, 클라우드 제공업체 API, 컨테이너 레지스트리, 일반적인 개발 도메인으로 구성된 기본 허용 목록에 접근할 수 있습니다.
- 클라우드 예약 작업의 양식 또는 클라우드 세션을 시작하는 환경 선택기에서 환경을 편집용으로 엽니다.
- Edit cloud environment 대화 상자에서 Network access 아래의 Limited를 선택한 다음, 차단된 도메인을 Allowed domains에 추가합니다. 한 줄에 하나의 도메인을 입력합니다. 직접 추가한 도메인과 함께 기본 허용 목록도 허용하려면 Allow package managers를 선택합니다. 제한 없는 액세스를 원한다면 대신 Full을 선택합니다.
- Save changes를 클릭합니다. 다음 실행부터 업데이트된 허용 목록이 사용됩니다. 이미 열려 있는 클라우드 세션의 경우 네트워크 액세스 변경이 기존 세션에 적용되는 시점을 참조합니다.
The proxy refused the connection
이 메시지는 Claude가HTTPS_PROXY 또는 관련 프록시 변수에 설정한 프록시를 통해 아티팩트를 읽을 때 표시됩니다. 아티팩트 콘텐츠는 *.frame.claudeusercontent.com에서 제공되므로, Claude Code는 먼저 프록시에 해당 호스트로의 터널을 열어 달라는 CONNECT 요청을 보냅니다. 프록시가 거부하면 호스트에는 아무것도 도달하지 않으며, 메시지에 프록시의 HTTP 상태가 포함됩니다.
CONNECT에 대한 프록시의 응답입니다. 호스트는 응답한 적이 없으므로 각 상태는 서로 다른 해결 방법을 가리킵니다.
HTTP 407: 프록시가 필요한 자격 증명을 받지 못했습니다. 기본 인증에 나온 대로 프록시 URL에 자격 증명을 넣습니다.HTTP 403: 프록시가*.frame.claudeusercontent.com으로의 터널링을 거부합니다. 프록시 운영자에게 네트워크 액세스 요구 사항에 나열된 이 호스트를 허용해 달라고 요청합니다.HTTP 502같은 기타 상태: 호스트에 도달하지 못하는 등 프록시 자체의 이유로 터널을 열지 않았습니다. 프록시 로그에서 해당 상태를 찾아봅니다.- 상태 대신
unreadable reply: 프록시 주소에 있는 무언가가 HTTP 상태 줄로 응답하지 않았습니다. 해당 주소가 HTTP 프록시인지 확인합니다.
- 프록시 구성에 설명된 대로 프록시 변수의 주소와 자격 증명을 확인한 다음, Claude Code를 시작하는 셸에서 자신의 프록시 URL을 사용하여
curl -x http://proxy.example.com:8080 -I https://api.anthropic.com을 실행합니다. Windows PowerShell에서는curl.exe를 실행합니다. 이 확인이 같은 방식으로 실패하면 먼저 프록시 설정을 수정합니다. 성공한다면 거부는 아티팩트 호스트에 국한된 것입니다. - 네트워크에서 Claude Code가 아티팩트 호스트에 직접 접근할 수 있다면
.frame.claudeusercontent.com을NO_PROXY에 추가합니다. 항목은 이렇게 좁게 유지합니다. 더 넓은.claudeusercontent.com항목은bridge.claudeusercontent.com도 프록시를 우회하게 만드는데, IP 허용 목록을 사용하는 조직은 이 호스트를 프록시에 유지해야 합니다.
The cloud environments service returned an empty or unexpected response
Claude Code는 CLI에서 클라우드 세션을 만들거나/remote-env를 실행할 때 등 여러 시점에 클라우드 환경 목록을 요청합니다. 서버의 응답을 읽을 수 없으면 다음 메시지 중 하나를 표시합니다.
/remote-env 대화 상자의 couldn't list environments:처럼 접두사를 추가할 수 있습니다.
해결 방법:
- 작업을 다시 시도합니다. Claude Code는 매번 목록을 다시 요청합니다
- 메시지가 계속 표시되면 status.claude.com에서 진행 중인 장애가 있는지 확인합니다
Failed to fetch session from Sessions API
이 메시지는 Claude Code가 터미널로 가져오도록 요청한 클라우드 세션을 찾았지만 Anthropic 서버에서 대화 기록을 읽을 수 없어 세션을 열지 않았음을 의미합니다.claude --teleport, /teleport 실행 후 또는 /tasks 목록에서 세션을 선택한 후에 표시됩니다. claude --teleport <session-id>는 이 메시지를 출력하고 코드 1로 종료합니다.
해결 방법:
- 같은 Teleport를 다시 실행합니다. 같은 방식으로 실패하면 문제를 보고합니다
Couldn’t load the history of cloud session
이 메시지는 Claude Code가 터미널로 가져오도록 요청한 클라우드 세션을 찾았지만, 대화 기록 요청이 찾을 수 없음으로 반환되었음을 의미합니다.- 메시지에 있는 링크를 열어 브라우저에서 세션을 확인합니다. 브라우저에서는 열리는데 같은 Teleport가 다시 이렇게 실패하면 문제를 보고합니다.
Couldn’t reconnect to your Remote Control session
claude --resume 또는 claude --continue로 재개하면 해당 대화에 기록된 Remote Control 세션에 다시 연결됩니다. 이 메시지는 네트워크 중단이나 서버 오류처럼 일시적일 수 있는 이유로 재연결이 실패하여, Claude Code가 원격 세션이 아직 존재하는지 확인할 수 없음을 의미합니다. 로컬 세션은 Remote Control 없이 계속 실행됩니다.
해결 방법:
/remote-control을 실행하여 연결을 재시도합니다claude --remote-control로 새 세션을 시작하여 새 Remote Control 세션을 만듭니다- 기타 Remote Control 시작 메시지는 Remote Control 문제 해결을 참조합니다
Previous session is unavailable — run /remote-control to start a new one을 표시합니다.
Sessions ended while this machine was offline
Claude Code는 머신이 오프라인 상태로 오래 있어서 서버가 해당 머신이 제공하던 Remote Control 환경을 정리한 후,claude remote-control을 실행 중인 터미널에 이 메시지를 표시합니다. 해당 환경의 세션은 종료되었으며 재개할 수 없습니다. 숫자는 종료된 세션의 수입니다.
- Claude Code가 이 메시지 아래에 보존된 워크트리를 나열하면, 그곳에서 커밋되지 않은 작업을 가져옵니다
claude remote-control을 실행하여 새 환경을 시작합니다
Couldn’t share the transcript
세션 품질 설문 같은 설문 프롬프트에서 세션 트랜스크립트 공유에 동의하면, Claude Code는 이를 Anthropic에 업로드합니다. 단, 서드파티 제공업체, Claude apps gateway 세션, 그리고 Anthropic 자격 증명을 사용할 수 없는 경우에는 대신 로컬 아카이브를 저장합니다. 이 메시지는 공유가 완료되지 않았음을 의미합니다./feedback을 실행하여 무슨 일이 있었는지 설명과 함께 트랜스크립트를 보냅니다. 사용 중인 환경에서/feedback을 사용할 수 없다면 오류 보고를 참조합니다- 다른 요청도 실패하고 있다면 네트워크 연결을 확인하고 Unable to connect to API를 참조합니다
Couldn’t send feedback
Couldn't send feedback으로 시작하는 메시지는 /feedback, /bug 또는 /share 대화 상자에서 제출한 보고서나 대기 중인 피드백 초안을 피드백 서비스가 확인하지 않았음을 의미합니다. 수신되지 않은 것으로 간주하십시오. 콜론 뒤에 조직에 관한 문장이 이어지면, 조직이 피드백을 거부하는 것입니다.
두 번째 예시는 조직의 거부입니다.
- 로그인하지 않음: 메시지가
: not signed in. Run /login, then retry.로 이어집니다./login을 실행한 다음 다시 보냅니다 - 조직의 거부: 예를 들어
: Feedback has not been enabled for your organization.또는: Feedback collection is not available for organizations with custom data retention policies.입니다. 이후 7일 동안/feedback이 조직의 정책에 의해 비활성화되었다고 응답할 수 있습니다. 대기 중인 초안은 대기 상태로 남아 있으며 여전히 예정대로 만료됩니다 - 거부된 자격 증명: 메시지가
: the sign-in this session uses is not allowed to send feedback또는: the server did not accept the credentials this session uses로 이어집니다. Claude Code 프롬프트에서/status를 실행하여 이 세션이 보내는 로그인, 토큰 또는 API 키를 확인합니다 Couldn't send feedback바로 뒤에(request timed out)또는(couldn't reach the service): 보고서나 대기 중인 초안을 다시 보냅니다. 대화 상자는 입력한 텍스트를 유지하며, 대기 중인 초안의 메시지에는The draft is still queued.라고 표시됩니다. 다른 요청도 실패하고 있다면 네트워크 연결을 확인하고 Unable to connect to API를 참조합니다. 계속 실패하면 github.com/anthropics/claude-code/issues에 보고서를 제출합니다Couldn't send feedback바로 뒤에(server returned <status>)또는 이유 없음: 상태는 서비스의 응답 코드입니다. 서비스가 자체 메시지를 보낸 경우(server returned 403: Access Forbidden)처럼 그 뒤에 이어집니다. 계속 실패하면 github.com/anthropics/claude-code/issues에 보고서를 제출합니다
Feedback payload too large
피드백 초안의 검토 화면에 표시되는 이 메시지는 서비스가 초안을 수락했다는 확인을 Claude Code가 받지 못했음을 의미합니다. 수신되지 않은 것으로 간주하십시오. 초안은/feedback 대기열에 남아 있으므로 다시 보낼 수 있습니다.
- 검토 화면에서 Send transcript를
no로 설정한 다음 초안을 다시 보냅니다. 세부 정보를 줄여도 제거되는 텍스트는 최대 10 KB이며, 이는 초안의 세부 정보가 담을 수 있는 최대 크기입니다.
절전 또는 시계 변경 중 MCP 서버 연결 시간 초과
이 메시지는 MCP 서버에 대한 연결이 시간 초과되었으며, Claude Code가 시도 중에 시스템 시계가 앞으로 건너뛴 것을 발견했음을 의미합니다.- 대화형 세션에서:
/mcp를 실행하고 서버를 선택한 다음 Reconnect를 선택합니다 - 셸에서:
claude -p,claude mcp list또는claude mcp get명령을 다시 실행합니다. 그 후 서버가Skipping connection (recent failure cached로 시작하는 메시지와 함께 실패하면 15분 기다린 후 명령을 다시 실행합니다. - Agent SDK 애플리케이션에서: TypeScript에서는
reconnectMcpServer()를, Python에서는ClaudeSDKClient.reconnect_mcp_server()를 호출합니다 - 서버가 다시 실패하는 경우: 메시지가 이것과 다르다면 MCP 서버가 연결되지 않을 때 확인할 사항을 참조합니다. 컴퓨터가 절전 모드에 들어가지 않았고 아무것도 시계를 변경하지 않았는데도 이 메시지가 다시 나타나면 오류 보고를 참조합니다.
MCP server "<name>" connection timed out after <N>ms 같은 시간 초과 메시지를 표시했습니다.
요청 오류
이 오류는 요청 내용과 관련됩니다. 대부분은 API가 요청을 거부한 후 API에서 반환되며, 일부는 요청이 전송되기 전에 Claude Code가 로컬에서 생성합니다.Prompt is too long
대화와 첨부 파일을 합한 크기가 모델의 컨텍스트 윈도우를 초과합니다.DISABLE_COMPACT가 설정되어 있으면 이 줄에는 /clear만 표시됩니다. 아래의 압축 실패 형식과 같은 더 긴 형식의 오류는 Prompt is too long · 문구를 유지합니다. -p 출력과 트랜스크립트에서는 텍스트가 Prompt is too long으로 유지됩니다.
사용자 설정에서 자동 압축을 끈 경우 이 줄에 해당 내용도 함께 표시됩니다:
/config의 Auto-compact 토글은 사용자 설정에 autoCompactEnabled를 기록합니다. 이 힌트는 /config 변경이 실제로 적용될 수 있는 경우에만 표시됩니다. 예를 들어 DISABLE_AUTO_COMPACT 또는 DISABLE_COMPACT로 자동 압축을 끈 경우에는 표시되지 않습니다. 또한 프로젝트 설정이나 관리형 설정처럼 우선순위가 더 높은 범위에서 autoCompactEnabled를 false로 설정한 경우에도 표시되지 않습니다. v2.1.235 이전에는 이 줄에 자동 압축 힌트가 없었습니다.
Amazon Bedrock은 이 상태를 Input is too long for requested model.로 보고하며, Claude Code는 이를 동일하게 처리합니다. v2.1.217 이전에는 Claude Code가 Bedrock의 문구를 인식하지 못해 자동 압축이 트리거되지 않았고 /compact도 같은 오류로 실패했습니다.
Claude apps gateway는 클라우드 업스트림이 제공업체 고유의 오류 형식으로 요청을 거부하면 이 상태를 capability_rejected: prompt_too_long으로 보고합니다. Claude Code는 이 토큰을 Prompt is too long과 동일하게 처리합니다. v2.1.228 이전에는 Claude Code가 이 토큰을 인식하지 못해 자동 압축이 트리거되지 않았습니다.
이번 턴에서 자동 압축이 실행되었지만 모델을 사용할 수 없거나 인증에 실패하는 등 근본 오류로 인해 실패한 경우, 메시지의 구분 기호 뒤에 해당 오류가 표시됩니다:
/compact도 같은 오류로 실패합니다. v2.1.229 이전에는 자동 압축이 실패해도 원인 없이 Prompt is too long만 표시되었습니다.
이 오류에서 자동 압축이 실행되면 일반적으로 가장 오래된 대화 교환을 요약하고 최신 교환은 유지합니다. 최후의 수단으로 Claude Code는 다른 방식으로 요약합니다:
- 전체 교환을 하나도 요약할 수 없는 경우 Claude Code는 최신 프롬프트를 그대로 유지하고 그 이전의 모든 내용을 요약합니다.
- 이 경우 대화가 사용자의 프롬프트로 끝나지 않으면 Claude Code는 대신 대화 전체를 요약합니다.
/clear를 실행하여 새로 시작하세요. v2.1.269 이전에는 전체 교환을 요약할 수 없을 때마다 압축이 실패했기 때문에, 이 상태의 세션에서는 매 턴마다 이 오류가 다시 발생했습니다.
교환이 하나뿐인 대화에는 요약할 이전 턴이 없습니다. 이러한 대화에서 자동 압축이 실행될 상황이 되면 Claude Code는 시도를 건너뛰고, 대신 요청을 채우고 있는 내용이 무엇인지 설명합니다. API가 오류에서 토큰 수를 보고하지 않으면 메시지는 다음과 같습니다:
Prompt is too long만 표시했습니다.
해결 방법:
/compact를 실행하여 이전 턴을 요약하고 공간을 확보하거나,/clear를 실행하여 새로 시작하세요./compact가Not enough messages to compact.로 응답하면 대화가 요약할 이전 내용이 없는 단일 교환이라는 뜻이므로, 공간은 해당 프롬프트 하나와 Claude Code가 모든 요청과 함께 보내는 내용이 차지하고 있습니다./clear를 실행하고 붙여넣는 텍스트를 줄이거나 더 작은 첨부 파일로 다시 보내거나, 아래 단계에 따라 도구 정의와 메모리 파일을 줄이세요/context를 실행하여 윈도우를 차지하는 항목(시스템 프롬프트, 도구, 메모리 파일, 메시지)의 내역을 확인하세요- 사용하지 않는 MCP 서버를
/mcp disable <name>으로 비활성화하여 해당 도구 정의를 컨텍스트에서 제거하세요 - 큰
CLAUDE.md메모리 파일을 줄이거나, 관련 있을 때만 로드되는 경로 범위 규칙으로 지침을 옮기세요 - 자동 압축은 기본적으로 켜져 있으며 일반적으로 이 오류를 방지합니다.
/config또는DISABLE_AUTO_COMPACT로 자동 압축을 끈 경우 다시 켜세요. 계속 꺼 두려면 윈도우가 가득 차기 전에 직접/compact를 실행하세요. - Claude Code가 모델 ID를 인식하지 못한다고 경고한 경우, 경고에 Claude Code가 가정한 윈도우 크기가 표시될 수 있습니다. 모델의 실제 윈도우가 이와 다르면 Claude Code에 실제 윈도우를 알려 주십시오.
- 사용자 지정
ANTHROPIC_BASE_URL을 사용하고 오류가Prompt is too long · automatic compaction failed로 시작하면 모델의 컨텍스트 윈도우를 설정하거나 v2.1.299 이상으로 업데이트하십시오. v2.1.299 이전에는 Claude Code가 가정된 200K 윈도우 근처에서 요청을 보내지 않고 이 메시지와 함께 턴을 종료했습니다.
- 사용자 지정
- Claude가 대화를 압축하는 동안 중지한 직후에 오류가 나타났다면, 대화는 변경되지 않았으며 여전히 압축이 필요할 만큼 큽니다.
/compact를 실행하고 메시지를 다시 보내세요. 오류가 재발하지 않도록 하려면 v2.1.304 이상으로 Claude Code를 업데이트하세요. v2.1.304 이전에는 이 시점에 중지하면 이 오류와 함께 턴이 종료될 수 있었습니다. - v2.1.305에서 MCP 도구가 많고 Anthropic API에 직접 연결된 경우, 이 오류가 API의 관련 없는 400 또는 422 오류를 가릴 수 있습니다. 원래 오류를 확인하려면 v2.1.306 이상으로 Claude Code를 업데이트하세요.
Context exceeds the token limit
대화가 모델의 컨텍스트 윈도우를 넘어서면/context는 출력 상단에 다음 경고를 표시합니다:
Context exceeds 경고가 표시된 후에도 자동 압축이 켜져 있는 동안(기본값)에는 두 명령 중 어느 것도 실행할 필요가 없습니다:
- 자동 압축 켜짐: 다음 메시지를 보내세요. 여전히
Prompt is too long으로 실패하면 해당 항목을 참조하세요. - 자동 압축 꺼짐: 세션에서 경고에
/compact가 표시되어 있으면 이를 실행하거나,/clear를 실행하여 다시 시작하세요. 둘 중 하나를 실행하기 전까지는 메시지가Context limit reached(-p출력에서는Prompt is too long)로 실패합니다.
DISABLE_COMPACT를 설정한 경우 두 형식 모두 /compact 대신 /clear를 표시합니다.
해결 방법:
- 압축 윈도우 경고 후: 여러 턴으로 이루어진 대화에서는
/compact를 실행하여 이전 턴을 요약하고 공간을 확보하세요. 대신 새로 시작하려면/clear를 실행하세요. - 사용량을 줄이는 다른 방법은 Prompt is too long을 참조하세요
/context가 100%를 넘는 사용량을 표시하면서도 그 의미나 복구 방법을 설명하는 경고 줄을 표시하지 않았습니다.
Request too large
원시 요청 본문이 토큰화 전에 API의 32MB 한도를 초과했습니다. 대개 크게 붙여넣은 내용, 도구 결과 또는 첨부 파일 때문입니다. 이 한도는 컨텍스트 윈도우와는 별개입니다.Request too large (max 32MB; 20.1MB of about 33.4MB is images or documents).: 이미지나 문서 때문에 요청이 한도를 초과했습니다. Claude Code는 이를 제거하고 재시도합니다.Request too large for the API's 32MB request limit: 메시지만으로도 한도를 초과하므로, 메시지에compacting cannot make it fit이 표시되고 Claude Code는 재시도하지 않습니다. 비대화형 모드에서는 메시지가 대신 입력을 줄이거나 새 세션을 시작하라고 안내합니다.
Request too large (max 32MB). Double press esc to go back and try with a smaller file.로 실패했습니다. v2.1.229 이전에는 압축이 도움이 되지 않는 경우에도 Claude Code가 모든 거부에 대해 첨부 파일 관련 조언을 표시했습니다.
해결 방법:
- 메시지에
compacting cannot make it fit이 표시되면 Esc를 두 번 눌러 큰 내용을 추가한 턴 이전으로 돌아가거나,/clear를 실행하여 새로 시작하세요 - 그렇지 않으면 누적된 이미지와 첨부 파일을 제거하는
/compact를 실행하세요 - 큰 파일은 내용을 붙여넣는 대신 경로로 참조하여 Claude가 나누어 읽을 수 있도록 하세요
- 이미지의 경우 아래 Image was too large를 참조하세요
Image was too large
붙여넣거나 첨부한 이미지가 API의 크기 또는 치수 한도를 초과합니다.could not be processed and was removed 줄은 API가 대화의 이미지(예: 크기 또는 치수 한도를 초과한 이미지)를 거부했음을 의미합니다.
이러한 오류 중 하나가 계속 반복되면 Claude Code를 업데이트하세요. 이전 버전에서는 다음과 같은 이유로 이미지 오류가 반복될 수 있었습니다:
- v2.1.299 이전에는 이미지가 많은 긴 대화에서 Claude Code가 한도를 초과한 이미지 대신 마지막으로 첨부한 이미지를 제거할 수 있었습니다. 그러면
was removed줄이 매 턴마다 반복되었고, Claude는 새 이미지를 보지 못했습니다. - v2.1.299 이전에는 VS Code, Desktop 앱, Agent SDK에서 Claude가 작업하는 동안 첨부한 이미지가 다른 첨부 이미지처럼 크기 조정되지 않았습니다. 이러한 이미지는 원래 크기로 API에 전달되어 긴 대화에서 이미지 오류가 반복되는 원인이 되었습니다.
- v2.1.166 이전에는 붙여넣은 이미지가 대화에 남아 이후 모든 메시지에서 같은 오류가 반복될 수 있었습니다
- 붙여넣기 전에 이미지 크기를 조정하세요. API는 단일 이미지의 경우 가장 긴 변이 최대 8000픽셀, 컨텍스트에 이미지가 20개를 넘는 경우 최대 3000픽셀인 이미지를 허용합니다.
- 전체 화면 대신 관련 영역만 좁게 스크린샷을 찍으세요
dimension limit for many-image requests메시지의 경우, 메시지에/compact가 표시되어 있으면 Claude Code 프롬프트에서 이를 실행하거나, 이미지를 줄여 새 세션을 시작하세요
dimension limit for many-image requests 메시지에는 API 오류에 명시된 픽셀 한도가 표시됩니다.
Unable to resize image
Claude Code가 첨부된 이미지를 API로 보내기 전에 축소하지 못했습니다.2000x2000px 대신 2576x2576px와 같은 다른 픽셀 한도가 명시될 수 있습니다.
해결 방법:
- 메시지에서 이미지 변환을 요청하면 PNG, JPEG, GIF 또는 WebP로 변환한 후 다시 첨부하세요. Claude Code는 이러한 형식의 경우 이미지를 디코딩하지 않고도 파일 헤더에서 치수를 확인할 수 있습니다.
- 메시지에 치수 또는 크기 한도가 표시되면 첨부하기 전에 이미지를 해당 한도 미만으로 크기 조정하거나 다시 압축하세요.
- 메시지에 CMYK JPEG, 애니메이션 WebP, 손상되었을 수 있는 파일과 같은 원인이 명시되어 있으면 메시지가 제안하는 형식으로 이미지를 다시 저장한 후 다시 첨부하세요.
Request rejected as unprocessable by the model
API가 모델이 처리할 수 없는 요청으로 판단하여 요청을 거부했습니다. 이 메시지는 API 자체의 메시지입니다.- 이미지나 문서가 있는 대화에서 메시지가 계속 나타나면 직접 제거하세요. Esc를 두 번 눌러 해당 항목을 추가한 턴 이전으로 돌아가거나,
/clear를 실행하여 새로 시작하세요.
PDF 오류
첨부한 PDF를 처리할 수 없었습니다. 여기에 표시된 메시지는 비대화형 형식이며, 대화형 세션에서는 대신 esc를 두 번 눌러 다시 시도하라는 안내가 표시됩니다.- 크기가 큰 PDF의 경우 전체 파일을 첨부하는 대신 Claude에게 Read 도구로 페이지 범위를 읽도록 요청하거나,
pdftotext같은 도구로 텍스트를 추출한 후 출력 파일을 경로로 참조하세요 - 보호되었거나 유효하지 않은 PDF의 경우 암호를 제거하거나 원본 애플리케이션에서 파일을 다시 내보낸 후 다시 시도하세요
pdftoppm으로 페이지를 렌더링합니다. 메시지에 제시된 명령으로 poppler-utils를 설치하거나, 다른 플랫폼에서는 pdftoppm을 PATH에 추가하는 poppler 빌드를 설치하세요. 어떤 PDF가 페이지 범위로 읽히는지는 Read 도구 동작을 참조하세요.
Extra inputs are not permitted
요청을 받은 엔드포인트가 요청의 필드 중 하나를 허용하지 않는 입력으로 판단하여 거부했으며, 엔드포인트의 메시지에 해당 필드가 명시됩니다.context_management 및 도구 검색의 defer_loading과 같은 베타 전용 필드를, 이를 활성화하는 anthropic-beta 헤더와 함께 보냅니다. 게이트웨이가 본문은 전달하지만 헤더를 제거하면 API는 인식할 수 없는 필드를 받게 됩니다. 게이트웨이가 Anthropic 형식의 본문을 다른 스키마를 사용하는 업스트림으로 전달하면 해당 업스트림이 이러한 필드를 거부합니다. 베타 헤더와 본문 필드 쌍에서 두 경우를 모두 다룹니다.
해결 방법:
- 메시지에
context_management: Extra inputs are not permitted가 포함되어 있으면 v2.1.304 이상으로 Claude Code를 업데이트하세요. 업데이트 후에는 Claude Code가 이 거부에 대응하여 해당 필드 없이 요청을 한 번 더 보냅니다. v2.1.304 이전에는 Claude Code가 이 거부에 대해 재시도하지 않았습니다. - 메시지에
defer_loading또는tool_reference가 명시되어 있으면 v2.1.305 이상으로 Claude Code를 업데이트하세요. 그러면 Claude Code는 이 거부에 대응하여 도구 검색 필드 없이 요청을 한 번 더 보냅니다. - 게이트웨이가 헤더를 제거하는 경우
anthropic-beta헤더를 전달하도록 구성하세요. 게이트웨이가 전달해야 하는 항목은 기능 패스스루를 참조하세요. - 대체 방법으로, 실행하기 전에
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1을 설정하세요. 정확한 적용 범위는 출시 전 기능 비활성화에서 다룹니다.
diagnostics 필드가 명시될 수 있었습니다. 이 오류는 이미 Anthropic API를 사용한 세션이 재시작 없이 Amazon Bedrock 또는 Google Cloud의 Agent Platform으로 전환될 때 나타났습니다. 예를 들어 열어 둔 세션은 다른 Claude Code 창에서 /setup-bedrock을 실행하면 Bedrock으로 전환됩니다. 해당 버전에서는 그 세션에서 /clear를 실행하거나 세션을 재시작하세요.
도구 입력 스키마가 유효하지 않음
요청의 도구가 API의 JSON Schema 검증을 통과하지 못하는input_schema를 선언하여 API가 요청 전체를 거부했습니다. tools. 뒤의 숫자는 요청의 도구 목록에서 실패한 도구의 위치이며, 조회할 수 있는 이름이 아닙니다.
$schema에서 draft 2020-12 이외의 JSON Schema 방언을 선언하는 스키마를 가진 도구에서도 발생할 수 있습니다. Claude Code는 이러한 스키마를 JSON Schema 메타 스키마와 대조하여 검사하지 않지만, 최상위 속성 이름 검사는 여전히 적용됩니다.
v2.1.216 이전에는 어떤 배포에서도 제외 검사가 실행되지 않았습니다.
해결 방법:
- Claude Code 버전이 v2.1.300 이전이면 셸에서
claude update를 실행하세요. v2.1.300 이전에는 Claude Code가 거부된 도구의 매개변수 없이 요청을 재시도하지 않았기 때문에, 해당 도구를 포함한 모든 요청에서 이 오류가 반복되었습니다. - 유효하지 않은 스키마를 선언하는 MCP 서버를 제거하거나 비활성화하세요. 오류는 도구를 위치로만 나타냅니다. v2.1.216 이상에서는 각 서버의 로그에서 입력 스키마가 거부될 도구를 명시하는 줄을 확인하세요. 이를 명시하는 로그가 없으면 서버를 하나씩 비활성화하세요.
- 서버를 유지 관리하는 경우 도구의
input_schema를 수정하세요. 스키마는 유효한 JSON Schema여야 하며, 최상위 속성 이름은 1~64자여야 하고 ASCII 문자와 숫자,_,.,-만 사용해야 합니다. 유효하지 않은 입력 스키마를 가진 도구를 참조하세요.
128자를 초과하는 MCP 도구 이름
MCP 서버가mcp__<server>__<tool>과 같은 전체 이름이 API가 허용하는 128자보다 긴 도구를 나열합니다. Claude Code는 Claude에게 보내는 도구에서 해당 도구를 제외하며, 서버의 다른 도구는 계속 작동합니다. 셸에서 claude --debug로 시작한 세션에서는 Claude Code가 ~/.claude/debug/<session-id>.txt의 디버그 로그에 다음 메시지를 기록합니다:
- 서버를 유지 관리하는 경우 도구 이름을 줄이세요.
- 서버가 MCP 구성에 있는 경우 그곳에서
analytics-database대신db처럼 더 짧은 이름을 지정하세요. 그런 다음 권한 규칙과 훅 matcher 등 이전 이름으로 서버나 해당 도구를 참조하는 항목을 업데이트하세요. - 플러그인이 서버를 번들로 제공하는 경우 도구의 전체 이름에는 플러그인 이름도 포함됩니다. 플러그인 유지 관리자에게 서버 또는 도구 이름을 줄여 달라고 요청하세요.
API Error: 400 ... tools.N.custom.name: String should have at most 128 characters로 거부했습니다.
200자를 초과하는 tool_use.name
대화 기록의 도구 호출에 API가 요청에서 허용하는 200자보다 긴 이름이 포함되어 있습니다:No such tool available 도구 오류로 실패하고 대화는 이 API 오류 없이 계속됩니다.
해결 방법:
claude update를 실행한 후 대화를 재개하세요. 업데이트된 버전은 트랜스크립트를 로드할 때 지나치게 긴 이름을 복구하므로, 막혀 있던 대화가 다시 작동합니다.
/compact와 --resume을 포함하여 대화를 다시 보내는 모든 요청을 거부했기 때문에 이 오류가 반복되고 대화가 막혔습니다.
There’s an issue with the selected model
구성된 모델 이름을 인식할 수 없거나 계정에 해당 모델에 대한 액세스 권한이 없습니다. v2.1.160부터 끝부분의 힌트(여기서는 대화형 형식으로 표시)는 사용 환경에 따라 다릅니다.- 대화형 CLI:
/model을 실행하여 계정에서 사용할 수 있는 모델 중에서 선택하세요. - 비대화형 모드(
-p): 유효한 별칭이나 ID와 함께--model을 전달하거나ANTHROPIC_MODEL을 설정하세요. 이 사용 환경에서는 오류 텍스트에Run --model이 표시됩니다. - Agent SDK: 모델이 프로그래밍 방식으로 설정되므로 오류 텍스트에서 힌트가 생략됩니다. TypeScript에서는
Options의model을, Python에서는ClaudeAgentOptions(model=...)을 설정하고, 구조화된model_not_found오류를 처리하여 자체 재시도 또는 모델 선택기를 표시하세요. - 전체 버전 ID 대신
sonnet또는opus와 같은 별칭을 사용하세요. 별칭은 유지 관리되는 기본값으로 확인되므로 오래된 값이 되지 않습니다. 모델 구성을 참조하세요. - CLI에서 잘못된 모델이 계속 다시 나타나면 어딘가에 오래된 ID가 설정되어 있는 것입니다. 우선순위 순서에 따라 모델을 설정할 수 있는 위치를 확인하고 오래된 값을 제거하세요.
- v2.1.206 이전에는 더 이상 갱신할 수 없는 만료된 claude.ai 로그인으로 인해 모든 모델이 이 오류로 실패했습니다. 해당 버전에서는
/login을 실행하세요. ANTHROPIC_BASE_URL이 LLM 게이트웨이를 가리키고 모든 모델이 이렇게 실패하면, 게이트웨이와 해당 업스트림이 도구 검색 필드를 허용하는지 확인하세요. 기본적으로 Claude Code는defer_loading도구 필드와tool_reference블록을 이를 활성화하는anthropic-beta헤더와 함께 보냅니다. v2.1.304 이전에는ENABLE_TOOL_SEARCH로 직접 켠 경우를 제외하고 게이트웨이 뒤에서 도구 검색이 꺼져 있었습니다.- Google Cloud의 Agent Platform 배포의 경우 Google Cloud의 Agent Platform 문제 해결을 참조하세요.
Model is not a recognized model id
모델 전환에 전달한 문자열은 Claude Code가 모델로 사용할 수 있는 문자열이 아니므로, Claude Code는 요청을 보내지 않고 전환을 거부했으며 세션은 현재 모델을 유지합니다. 이 오류는 Agent SDKsetModel() 메서드나 Desktop 앱처럼 Claude Code CLI를 대신 실행하는 앱을 통해 모델을 설정하거나, Remote Control로 연결된 기기에서 모델을 선택할 때 발생할 수 있습니다. v2.1.200 이전에는 Claude Code가 문자열을 저장했다가 다음 요청에서 There’s an issue with the selected model로 실패했습니다.
Sonnet 5를 보냈으며, 메시지는 이를 공백 없이 반복합니다. 끝부분의 힌트에는 가장 가깝게 일치하는 별칭 또는 모델 ID가 표시됩니다. 충분히 가까운 항목이 없으면 대신 Run /model to see available models.가 표시됩니다. Desktop 앱이 대신 시작하는 세션에서는 일치 항목이 없을 때의 힌트가 Switch to a different model.로 표시됩니다.
Anthropic API에서 Agent SDK나 앱을 통해 전환하는 경우, 표시 이름이나 빈 문자열처럼 모델 ID가 될 수 없는 문자열에만 이 오류가 발생합니다.
Remote Control 기기에서 모델을 선택하면 Claude Code가 로컬에서 문자열을 확인합니다. 모델 별칭, Claude Code가 나열하거나 사용자가 구성한 모델, 또는 claude-로 시작하는 ID가 아닌 모든 문자열에는 이 오류가 발생하며, claud-sonnet-5와 같이 잘못 입력한 ID도 포함됩니다. v2.1.260 이전에는 이 검사가 Remote Control 선택에 적용되지 않아, 인식되지 않는 문자열이 적용된 후 다음 요청에서 실패했습니다.
해결 방법:
- 인수 없이
/model을 실행하여 선택기를 열고 계정에서 사용할 수 있는 모델 중에서 선택한 다음, 그곳에 표시된 별칭이나 ID를 전달하세요 - 최신 Claude Code 버전에서만 지원하는 별칭을 사용한 경우
claude update를 실행하거나 대신 모델의 전체 ID를 전달하세요. 서버는 여전히 해당 모델에 대해 최소 Claude Code 버전을 요구할 수 있습니다. Claude Code does not support this model을 참조하세요. - v2.1.200 이전에 저장된 모델은 이 검사로 복구되지 않습니다. 오래된 값이 계속 다시 나타나면 모델 설정에 나열된 위치에서 제거하세요.
- Anthropic API 이외의 제공업체나 게이트웨이 또는 사용자 지정
ANTHROPIC_BASE_URL뒤에서는 빈 문자열에만 이 오류가 발생합니다. Claude Code는 모든 제공업체에서 요청 시점에 여전히 인식되지 않는 모델 진단 줄을 기록할 수 있습니다.
Model not found
이름으로 모델을 전환했지만 Claude Code가 해당 이름의 모델이 존재하는지 확인할 수 없었습니다. 이름이 모델 별칭이나 Claude Code가 로컬에서 허용하는 다른 표기가 아니면 Claude Code는 최소한의 API 요청으로 이를 확인하며, 이 오류는 대개 API 엔드포인트의 응답입니다./model <name>에서는 공백이 포함된 이름처럼 애초에 모델 ID가 될 수 없는 이름에도 같은 메시지가 표시됩니다.
Try '...' instead 제안이 추가될 수 있습니다.
해결 방법:
- 인수 없이
/model을 실행하여 계정에서 사용할 수 있는 모델 중에서 선택하거나, 유지 관리되는 기본값으로 확인되는sonnet과 같은 모델 별칭을 사용하세요 - 전체 ID를 입력한 경우 제공업체의 모델 카탈로그와 대조하세요. 새로 출시된 모델은 제공업체나 리전에서 제공되기 전에 Anthropic API에서 먼저 사용 가능할 수 있습니다.
- Agent SDK에서는
setModel()이 이 메시지와 함께 실패하고 세션은 이전 모델로 계속 실행됩니다. TypeScript SDK에서는supportedModels()를 호출하여 전환할 수 있는 모델 목록을 확인하세요. - v2.1.265 이전에는
/model이opusplan[1m]별칭 표기도 이 오류로 거부했습니다. 해당 버전에서는 Claude Code를 업데이트하거나, 대신 설정이나--model로 모델을 설정하세요.
Couldn’t confirm model with the API
Agent SDKsetModel() 메서드나 Desktop 앱처럼 Claude Code CLI를 대신 실행하는 앱을 통해 모델을 전환했는데, API 엔드포인트에서 모델 ID를 확인하는 요청이 15초 내에 응답을 받지 못했습니다. 세션은 현재 모델을 유지합니다.
Try again.으로 끝납니다.
해결 방법:
- 해당 모델로 다시 전환하세요
- 전환이 계속 실패하면 Claude Code가 API 엔드포인트에 연결할 수 있는지 확인하세요. 네트워크 및 연결 오류를 참조하세요
선택한 모델을 확인할 때 발생하는 API 오류
/model <name>으로 모델을 선택했거나 세션에 연결된 앱이 전환을 요청했습니다. API가 속도 제한이나 서버 오류처럼 별도 항목이 없는 이유로, Claude Code가 모델을 확인하기 위해 보내는 최소한의 요청을 거부했습니다. 세션은 현재 모델을 유지하며, 메시지 끝에서 이를 알립니다:
- 서버의 설명에 따라 조치하세요. 속도 제한이나 5xx 상태인 경우 잠시 기다린 후 모델을 다시 선택하세요
- 고유한 문구가 있는 거부는 Model not found와 Model is restricted by your organization’s settings 등 주변 항목에서 다룹니다
Claude Opus is not available with the Claude Pro plan
활성 구독 플랜에 선택한 모델이 포함되어 있지 않습니다.sign out and sign in again하라고 안내합니다.
해결 방법:
/model을 실행하고 플랜에 포함된 모델을 선택하세요- 최근에 플랜을 업그레이드했는데도 이 메시지가 표시되면
/logout을 실행한 후/login을 실행하세요. 저장된 토큰은 로그인 시점의 플랜을 반영하므로, claude.ai에서 업그레이드해도 다시 인증하기 전까지는 기존 세션에 적용되지 않습니다. - 각 플랜에 포함된 모델은 claude.com/pricing을 참조하세요
Claude Code does not support this model
Claude Code 버전이 필수 최소 버전보다 낮아 API가 400으로 요청을 거부했습니다. 선택한 모델이 더 새로운 버전을 요구하거나(서버가 모델별로 확인), 조직의 정책이 이를 요구합니다. 400 응답에는 오류 코드claude_code_version_too_old가 포함되며, 메시지에 어떤 최소 버전이 적용되는지 표시됩니다.
- stable 릴리스 채널에서
claude update를 실행하면 최신 stable 릴리스보다 새로운 버전으로는 업데이트되지 않으며, 이 릴리스는 여전히 필수 최소 버전보다 낮을 수 있습니다. latest 채널로 이동한 후 다시 업데이트하세요. 조직이 관리형 설정을 통해 채널이나 버전을 고정한 경우 관리자에게 변경을 요청하세요 - 모델별 문구의 경우 다른 모델로 전환하여 현재 세션에서 계속 작업할 수 있습니다. CLI에서
/model을 실행하거나, 스트리밍 입력 모드에서 TypeScript SDK의Query객체에 대해setModel()을 호출하거나, Python SDK의ClaudeSDKClient에 대해set_model()을 호출하세요 - 조직 정책 문구의 경우 계속하기 전에 업데이트하세요
Model is restricted by your organization’s settings
조직 관리자가 claude.ai 관리 콘솔에서 이 모델을 비활성화했거나, 관리형 설정이availableModels 허용 목록 또는 deniedModels 목록을 통해 이 모델을 제외합니다. 이 알림은 --model, ANTHROPIC_MODEL 또는 model 설정이 제한된 모델을 지정한 경우 시작 시 나타나며, 세션이 대신 사용하는 모델을 명시합니다. 관리형 설정으로 인해 세션이 사용할 수 있는 허용된 모델이 없는 경우 관리형 설정이 기본 모델을 차단함을 참조하세요. 관리자가 claude.ai 관리 콘솔에서 세션이 실행 중인 모델을 비활성화하면 대체 알림이 세션 도중에 나타날 수도 있습니다.
/model <name>을 입력하면 거부되며 세션은 현재 모델을 유지합니다. 관리 콘솔에서 비활성화된 모델의 경우 거부 메시지는 Model '<name>' is restricted by your organization's settings. Run /model to choose a different model.입니다. 관리형 설정이 제외하는 모델의 경우 Model '<name>' is not available. Your organization restricts model selection.입니다.
에이전트, 스킬 또는 명령 이름이 앞에 붙은 알림은 해당 서브에이전트가 요청한 모델에 제한이 적용되었음을 의미합니다. 서브에이전트는 대체된 모델로 실행되며 세션의 모델은 변경되지 않습니다. v2.1.223 이전에는 Claude Code가 Agent 도구로 시작된 서브에이전트에 대해서만 알림을 표시했습니다.
Claude Code는 opus, sonnet, haiku, fable 중 하나인 모델 패밀리 별칭을 해당 패밀리의 최신 버전이 아닌 패밀리 자체에 대한 요청으로 처리합니다. Anthropic API와 Claude Platform on AWS에서 제한된 패밀리 별칭은 조직의 설정이 허용하는 해당 패밀리의 최신 버전으로 확인되며, 대체 알림에 해당 버전이 명시됩니다. Claude Code는 패밀리의 모든 버전이 제한된 경우에만 /model <alias>를 거부합니다. v2.1.205 이전에는 같은 패밀리의 이전 버전이 허용되더라도 패밀리 별칭이 최신 버전만을 기준으로 대체되거나 거부되었습니다.
해결 방법:
/model을 실행하여 조직이 허용하는 모델 중에서 선택하세요. 제한된 모델은 선택기에서 숨겨집니다.- 제한된 모델이
--model,ANTHROPIC_MODEL, 설정 파일의model필드, 또는 서브에이전트, 스킬, 명령의modelfrontmatter에 설정된 경우, 알림이 반복되지 않도록 해당 값을 제거하거나 업데이트하세요 - 제한된 모델에 액세스해야 하는 경우 조직 관리자에게 활성화를 요청하세요. 조직 모델 제한을 참조하세요.
Can’t switch to the default model
예를 들어/model 선택기에서 Default 행을 선택하거나 /model default를 입력하여 Default 모델을 선택했습니다. Claude Code가 전환을 거부했으므로 세션은 현재 모델을 유지합니다.
your organization's managed settings block it ... in "deniedModels": 관리형 거부 목록이 Default 옵션이 확인되는 모델을 차단합니다your organization allows only the models listed in "availableModels":availableModelsMatch가"exact"로 설정된 관리형availableModels허용 목록에 Default 옵션이 확인되는 모델이 포함되어 있지 않습니다Claude Code couldn't read your organization's managed settings to check which models they allow: 관리형 설정을 읽을 수 없었으며, Claude Code는 확인되지 않은 상태로 전환을 적용하는 대신 전환을 거부합니다
deniedModels및availableModels문구의 경우/model을 실행하고 조직이 허용하는 모델을 이름으로 선택하세요- 메시지에 명시된 관리형 설정을 업데이트하도록 관리자에게 요청하세요
couldn't read문구의 경우 Claude Code를 재시작하세요. 계속 발생하면 관리자에게 관리형 설정을 확인하도록 요청하세요
Claude Code can't start 메시지와 함께 세션이 시작되지 않으면 관리형 설정이 기본 모델을 차단함을 참조하세요.
Model switch was blocked by a PreModelSwitch hook
PreModelSwitch 훅이 사용자나 클라이언트가 요청한 모델 전환을 승인하지 않아 세션이 현재 모델을 유지합니다. 직접 입력한 명령이 아닌 Agent SDK 호스트나 Remote Control에서 전환이 시작된 경우, 메시지는 대상 모델을 명시하지 않고Model switch blocked by a PreModelSwitch hook으로 표시됩니다.
- 훅이 작성한 이유: PreModelSwitch 훅이 전환을 거부하거나 확인을 요청할 때 해당 이유를 제공했습니다. 요청된 내용을 해결하거나 훅이 허용하는 모델을 선택하세요.
PreModelSwitch hook <name> did not respond before its timeout: 타임아웃 전에 응답하지 않는 훅은 전환을 차단합니다. 멈춘 명령을 수정하거나 해당 훅의timeout을 늘린 후 다시 전환하세요.confirmation required, and this session cannot ask: 훅이 이유 없이ask로 응답했으며, 제어 요청에는 확인 프롬프트를 표시할 방법이 없습니다.-p실행의/model명령은 같은 상태를 이유 뒤에(run /model interactively to confirm)을 붙여 보고합니다. 대화형 세션에서 전환하거나 이 모델에 대한 훅의 결정을 변경하세요.so organization-managed PreModelSwitch hooks could not be checked: v2.1.323 이전의 Claude Code는 관리형 플러그인이 제공하는 PreModelSwitch 훅을 파악할 수 없으면 전환을 거부합니다. 이 문구 앞의 텍스트는 무엇이 실패했는지 나타냅니다. 거부를 멈추려면 Claude Code를 업데이트하세요. 실패한 플러그인의 훅도 실행되도록 하려면 플러그인을 수정하거나 관리자에게 문의하세요. 자세한 내용을 확인하려면 셸에서claude --debug를 시작하고 모델을 전환한 다음 디버그 로그를 읽으세요.a PreModelSwitch hook failed before answering또는PreModelSwitch hooks were cancelled (the control stream closed) before answering: 훅 실행이 결정 없이 종료되었으며, Claude Code는 이를 승인으로 간주하지 않습니다.claude --debug를 실행하여 무엇이 실패했는지 확인한 후 다시 전환하세요.
plugin hooks could not be loaded, so PreModelSwitch hooks could not be checked; see the debug log였습니다. Claude Code는 플러그인 로드를 한 번 재시도한 후, 조직이 관리하는 플러그인이 없는 경우에도 세션에서 이후의 전환을 거부했습니다. 해당 버전에서는 세션을 재시작하여 플러그인 로드를 다시 실행하세요.
Couldn’t save it as your default
예를 들어/model <name> 또는 /model 선택기에서 Enter로 기본값으로 저장할 모델을 선택했지만, Claude Code가 선택 내용을 사용자 설정 파일인 ~/.claude/settings.json에 기록하지 못했습니다. 전환 자체는 적용되었으므로 현재 세션은 선택한 모델로 실행되지만, 기본값은 변경되지 않았으며 다음 세션은 이전 값으로 시작합니다.
can't be written (<code>): 쓰기가 괄호 안의 운영 체제 오류 코드와 함께 실패했습니다. 예를 들어 파일 또는 파일이 링크하는 대상 파일이 쓰기를 거부하는 파일 시스템에 있으면EROFS가 표시됩니다. 파일을 쓰기 가능하게 만든 후 다시 전환하세요. 다른 도구가 파일을 생성하는 경우 대신 해당 도구에서model키를 설정하세요. Claude Code에서 변경한 내용이 새 세션에서 사라짐을 참조하세요.isn't valid JSON: 디스크의 파일을 파싱할 수 없으며, Claude Code는 다시 읽을 수 없는 내용을 덮어쓰지 않도록 파일을 그대로 둡니다. 구문 오류를 수정한 후 다시 전환하세요. 손상된 설정 파일 수정을 참조하세요.
couldn't confirm it was saved as your default (~/.claude/settings.json is still being written)로 끝나는 알림은 3초가 지난 후에도 쓰기가 완료되지 않았음을 의미합니다. 쓰기는 백그라운드에서 계속되므로 기본값이 여전히 저장될 수 있습니다. 다음 세션이 어떤 모델로 시작하는지 확인하거나 /model <name>을 다시 실행하세요.
v2.1.265 이전에는 쓰기가 실패한 경우에도 알림에 모델이 saved as your default for new sessions되었다고 표시되었습니다.
Advisor is less capable than the current main model
어드바이저 모델의 순위가 세션의 메인 모델보다 낮으므로, Claude Code는 선택은 유지하지만 메인 모델의 요청에 어드바이저를 연결하지 않습니다.- 대화형 세션에서는
Advisor will not activate on the main model (advisor is less capable); subagents may still use it and may use more tokens · /advisor라는 알림이 표시됩니다. - 비대화형 모드에서
--advisor플래그로 실행하고 해당 실행이 백그라운드 세션이 아닌 경우, 경고가 stderr로 출력되고 실행은 그대로 시작됩니다. 경고 내용은"<advisor>" cannot advise "<main model>" (the advisor must be at least as capable as the main model). The advisor will not be used for the main model.입니다. 대화형 세션은 이 경고를 디버그 로그에만 기록합니다.
- 순위가 더 높은 어드바이저나 순위가 더 낮은 메인 모델을 선택하세요. 어드바이저 모델 선택에서 순위를 보여 주고 각 메인 모델에 허용되는 어드바이저를 나열합니다.
- 어드바이저가 자문할 수 있는 모델을 사용하는 서브에이전트가 계속 어드바이저를 사용하도록 하려면 어드바이저 설정을 그대로 두세요
thinking.type.enabled is not supported for this model
Claude Code 버전이 선택한 모델에 필요한 최소 버전보다 오래되었습니다. CLI가 모델이 더 이상 허용하지 않는 사고 구성을 보냈습니다.claude update를 실행하고 Claude Code를 재시작하세요. Opus 4.7은 v2.1.111 이상이 필요합니다. Opus 4.8은 v2.1.154 이상이 필요합니다. Sonnet 5는 v2.1.197 이상이 필요합니다. Opus 5는 v2.1.219 이상이 필요합니다. Opus 5.5는 v2.1.280 이상이 필요합니다. Sonnet 5.5는 v2.1.284 이상이 필요합니다- stable 릴리스 채널에서는 업데이트해도 최신 stable 릴리스보다 새로운 버전으로 이동하지 않으며, 이 릴리스는 여전히 이러한 버전보다 오래되었을 수 있습니다. latest 채널로 이동한 후 업데이트하세요
- 업그레이드할 수 없으면
/model을 실행하고 대신 Opus 4.6 또는 Sonnet 4.6을 선택하세요 - Agent SDK에서 이 문제가 발생하면 대신 SDK 패키지를 업그레이드하세요. Opus 4.8은 TypeScript SDK v0.3.154 이상 및 Python SDK v0.2.88 이상이 필요합니다. Sonnet 5는 TypeScript SDK v0.3.197 이상이 필요합니다. Opus 5는 TypeScript SDK v0.3.219 이상이 필요합니다. Opus 5.5는 TypeScript SDK v0.3.280 이상이 필요합니다. Sonnet 5.5는 TypeScript SDK v0.3.284 이상이 필요합니다
Effort isn’t available with thinking turned off
확장 사고를 끈 상태에서high보다 높은 effort 수준으로 실행했습니다. 모델이 이 조합을 허용하지 않으므로 API가 요청을 거부했습니다.
· 뒤의 힌트는 세션에 따라 다릅니다. 비대화형 세션에서는 use --effort high (or the effortLevel setting)로, Claude Desktop 앱이 실행하는 세션에서는 you can lower effort to High로 표시됩니다.
해결 방법:
- effort 수준을 낮춰
high이하로 설정하세요. - 예를 들어
MAX_THINKING_TOKENS설정을 해제하거나 설정에서"alwaysThinkingEnabled": false를 제거하여 사고를 다시 켜세요.
API Error: 400 output_config.effort 'xhigh' is not supported when thinking is disabled on this model. Use effort 'high' or below, or enable thinking. v2.1.251 이전에는 Claude Code가 설정한 effort 수준 그대로 요청을 보냈기 때문에, Opus 5는 사고가 꺼진 상태에서 high보다 높은 모든 요청을 거부했습니다. 이제 Claude Code는 Opus 5처럼 이 조합을 거부하는 것으로 알려진 모델에는 대신 effort high를 보냅니다.
사고 예산이 출력 한도를 초과함
구성된 확장 사고 예산이 최대 응답 길이를 초과하여 실제 답변을 위한 공간이 남지 않습니다.CLAUDE_CODE_MAX_OUTPUT_TOKENS를 사고 예산보다 높게 올리세요- 예산이 출력 길이와 어떻게 상호 작용하는지는 확장 사고를 참조하세요
Response exceeded the output token maximum
Claude의 응답이 요청에서 허용하는 최대 출력 토큰 수에 도달하여 그 지점에서 잘렸습니다:a request sent without streaming을 명시하는 형식은 스트리밍 요청이 실패하여 Claude Code가 스트리밍 없이 다시 보냈다는 의미이며, 이 경우 응답은 64,000 출력 토큰으로 제한됩니다. v2.1.299 이전에는 이렇게 다시 보낸 요청에서 응답이 잘리면 이 메시지 없이 응답이 완료된 것처럼 턴이 종료되었습니다.
해결 방법:
- 응답이 잘리기 전에 Claude가 일부 텍스트를 작성했다면, 대화형 세션에서
continue로 답하여 나머지를 요청하세요. 해당 텍스트는 대화에 남아 있습니다. - 메시지에서
CLAUDE_CODE_MAX_OUTPUT_TOKENS를 설정하라고 안내하면, 값의 상한이 어떻게 정해지는지는CLAUDE_CODE_MAX_OUTPUT_TOKENS를, 설정 위치는 환경 변수 설정을 참조하세요 - 각 응답을 한도 이내로 유지하려면 응답당 파일 하나 또는 섹션 하나처럼 더 작은 단위로 출력을 요청하세요
도구 사용 또는 thinking 블록 불일치
대화 기록이 일관되지 않은 상태로 API에 전달되었습니다.tool_use, tool_result, thinking 블록 순서가 더 이상 API가 예상하는 것과 일치하지 않습니다.
해결 방법:
- Opus 4.7 또는 Opus 4.8을 사용하는 경우 먼저
claude update를 실행하세요. v2.1.156 이전 버전은 일반적인 도구 사용 중에 이 오류를 일으킬 수 있으며,/rewind로는 해결되지 않습니다. /rewind를 실행하거나 Esc를 두 번 눌러 손상된 턴 이전의 체크포인트로 돌아간 후 그곳에서부터 계속하세요. 체크포인트가 생성되고 복원되는 방식은 체크포인트를 참조하세요.
Invalid data in redacted_thinking block
API가 대화 기록의 이전 턴에 포함된redacted_thinking 블록을 허용할 수 없어 400으로 요청을 거부했습니다.
- v2.1.281 이하를 사용 중이고 모든 턴이 이 오류로 실패하면
claude update를 실행하고 세션을 재개하세요 - 오류가 지속되면
/clear를 실행하여 해당 블록이 포함되지 않은 대화를 시작하세요
Unsupported tool content removed
Claude Code가 Anthropic API에 직접 연결된 상태에서 저장된 세션을 로드하거나 미리 볼 때, Anthropic API가 허용하지 않는 도구 콘텐츠를 제거하고, 제거된 콘텐츠가 두 thinking 블록 사이에 있던 자리에 다음 줄을 남깁니다:ANTHROPIC_BASE_URL로 설정되어 다른 제공업체의 도구 호출을 변환하는 서드파티 프록시입니다. Claude Code는 세션이 Anthropic API에 직접 연결된 경우에만 이를 제거하며, 세션이 프록시를 통해 또는 다른 제공업체에서 실행되는 경우에는 저장된 기록을 그대로 로드합니다. v2.1.246 이전에는 Claude Code가 도구 사용과 그 결과를 API로 다시 보냈고, 재개된 세션의 모든 턴이 messages.1.content.0.server_tool_use.name: Input should be 'web_search', 'web_fetch', ...와 같은 400 오류로 실패했습니다.
해결 방법:
- 자리 표시자 줄이 표시되는 경우에는 조치가 필요하지 않습니다. 세션은 제거된 콘텐츠 없이 계속됩니다.
- 대신 재개된 세션의 모든 턴이 400 오류로 실패하면
claude update를 실행하고 세션을 다시 재개하세요. v2.1.246 이전 버전은 콘텐츠를 제거하지 않습니다.
role ‘system’ must precede an ‘assistant’ message
시스템 메시지가 대화에서 API가 허용하지 않는 위치에 있어 API가 400으로 요청을 거부했습니다:use the top-level 'system' parameter for the initial system prompt와 같이 위치에 관한 API의 유사한 문구도 같은 방식으로 복구됩니다.
오류가 표시된다면 거부된 시스템 메시지는 Claude Code가 제거할 수 있는 메시지가 아닙니다. 이는 대개 Claude Code와 API 사이의 프록시나 LLM 게이트웨이가 자체 시스템 메시지를 추가했음을 의미합니다.
해결 방법:
ANTHROPIC_BASE_URL로 구성된 프록시나 게이트웨이 뒤에서 매 턴마다 오류가 반복되면, 프록시 없이 연결하여 원인을 확인하고 해당 프록시의 운영자에게 오류를 보고하세요/clear를 실행하여 새 대화를 시작하세요. 새 대화에서도 오류가 다시 발생하면 원인은 저장된 대화가 아니라 요청 경로에 있습니다.
Invalid encrypted_content in search_result block
대화 기록에 API가 복호화할 수 없는 호스팅 웹 검색 콘텐츠가 있어 API가 400으로 요청을 거부했습니다. 문구에는 읽을 수 없는 필드가 명시됩니다:encrypted_stdout 문구는 이러한 결과를 읽은 호스팅 코드 실행 프로그램의 출력을 가리키며, API는 이 출력도 암호화합니다. API는 다른 조직용으로 생성된 콘텐츠처럼 복호화할 수 없는 콘텐츠를 다시 보내는 요청을 거부합니다.
Claude Code 자체의 WebSearch 도구는 검색 결과를 일반 텍스트로 기록하므로, 이러한 블록은 대개 호스팅 웹 검색을 직접 실행한 프록시나 LLM 게이트웨이를 통해 대화에 들어옵니다.
세 가지 웹 검색 문구의 경우 Claude Code는 검색 호출, 결과, 인용을 보내는 내용에서 제외하고 요청을 한 번 재시도하므로, 세션은 오류를 표시하지 않고 계속됩니다. encrypted_stdout 문구에는 이러한 복구가 없으므로 해당 메시지는 여전히 표시됩니다. v2.1.282 이전에는 Claude Code가 거부된 웹 검색 블록도 유지했기 때문에 이후의 모든 턴과 /compact가 같은 방식으로 실패했습니다.
해결 방법:
- v2.1.281 이하를 사용 중이고 모든 턴이 웹 검색 문구 중 하나로 실패하면
claude update를 실행하고 세션을 재개하세요 - 오류가 지속되거나 메시지에
encrypted_stdout이 명시되어 있으면/rewind를 실행하여 해당 콘텐츠를 추가한 턴 이전의 체크포인트로 돌아가거나,/clear를 실행하여 해당 콘텐츠가 포함되지 않은 대화를 시작하세요 - 프록시나 게이트웨이 뒤에서 Claude Code를 실행하는 경우 해당 운영자에게 오류를 보고하세요
사용 정책 거부
대화의 콘텐츠가 사용 정책 검사를 트리거하여 API가 응답을 거부했습니다. 메시지에Details: `[reasoning_extraction]` 줄이 포함되어 있다면 안전 장치가 Claude의 추론을 요구하는 요청을 플래그 처리함을 참조하십시오.
메시지에는 Request ID와 Message ID가 포함되어 있으며, 거부가 잘못되었다고 판단되는 경우 지원팀에 문의할 때 이를 인용할 수 있습니다.
Claude가 표시됩니다.
이 검사는 최신 프롬프트뿐만 아니라 전체 대화를 평가하므로, 같은 세션에서 새 메시지를 보내면 대개 같은 거부가 다시 트리거됩니다. 세션을 종료한 후 --continue 또는 --resume으로 다시 열어도 마찬가지인데, 디스크의 트랜스크립트에 트리거한 콘텐츠가 여전히 포함되어 있기 때문입니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry에서는 모델의 안전 조치가 사이버 보안 주제로 플래그 처리한 요청에도 이 메시지가 표시됩니다. 안전 조치가 사이버 보안 주제를 플래그 처리함을 참조하십시오.
v2.1.219 이전에는 메시지가 Claude Code is unable to respond to this request, which appears to violate our Usage Policy (https://www.anthropic.com/legal/aup). Please double press esc to edit your last message or start a new session for Claude Code to assist with a different task.로 표시되었습니다.
해결 방법:
- Esc를 두 번 누르거나
/rewind를 실행하여 거부를 트리거한 턴 이전의 체크포인트로 되돌아간 다음, 표현을 바꾸거나 다른 접근 방식을 사용합니다. 체크포인트를 참조하십시오. - 어떤 턴이 원인인지 파악할 수 없다면
/clear를 실행하여 같은 프로젝트에서 새 대화를 시작합니다. 이전 대화는 디스크에 보존되며/resume에서 계속 사용할 수 있습니다. - 되감기를 사용할 수 없는 비대화형 모드(
-p)에서는--continue없이 새 세션에서 표현을 바꾼 프롬프트로 재시도합니다. 정책 검사는 모델마다 다르므로, 경우에 따라--model로 다른 모델로 전환하는 것도 거부를 해결할 수 있습니다.
안전 조치가 사이버 보안 주제를 플래그 처리함
모델의 안전 조치가 대화의 콘텐츠를 사이버 보안 주제로 플래그 처리했습니다. 메시지에는 요청을 플래그 처리한 모델의 이름이 표시됩니다.Details: `[reasoning_extraction]` 줄이 포함되어 있다면 안전 장치가 Claude의 추론을 요구하는 요청을 플래그 처리함을 참조하십시오.
이 메시지는 합법적인 사이버 보안 작업을 위한 액세스 권한을 부여하는 Cyber Verification Program으로 연결됩니다. 자동 모델 폴백이 있는 모델은 이 링크 없이 다른 메시지를 출력하며, Opus 5.5와 Sonnet 5.5에서는 <model>'s safeguards flagged this session으로 시작합니다. 해당 섹션에서는 Claude Code가 대신 모델을 전환하는 경우도 다룹니다.
Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry에서는 사이버 보안 플래그가 발생하면 대신 사용 정책 거부 메시지가 표시됩니다.
해결 방법:
- 작업에 이 콘텐츠가 필요한 경우 Cyber Verification Program을 통해 액세스를 신청합니다
- 요청이 사이버 보안 주제와 관련이 없었다면
/feedback을 실행하여 오탐을 신고합니다 - 같은 세션에서 계속 작업하려면 Esc를 두 번 누르거나
/rewind를 실행하여 플래그를 트리거한 턴 이전의 체크포인트로 되돌아간 다음, 다른 접근 방식을 사용합니다. 체크포인트를 참조하십시오.
- v2.1.219부터 v2.1.296까지는 메시지의 마지막 문장 앞에
Apply to the Cyber Verification Program to reduce these interruptions.가 포함될 수도 있었습니다 - v2.1.203부터 v2.1.218까지는 메시지가
<model> has safety measures that flagged this message for a cybersecurity topic. To learn about the Cyber Verification Program and apply for access, visit our help center:뒤에 동일한 도움말 센터 링크가 이어지는 형태로 표시되었습니다. 대화형 세션에서는 이어서If you were not engaging in a cybersecurity topic, please send feedback via /feedback.가 표시되었습니다 - v2.1.203 이전에는
<model>'s safeguards flagged this message for a cybersecurity topic. If your work requires this access, you can apply for an exemption:뒤에 예외 신청 양식 링크가 이어지는 형태로 표시되었습니다
안전 장치가 Claude의 추론을 요구하는 요청을 플래그 처리함
안전 장치가 해당 요청을 모델에게 내부 추론을 응답에 재현하도록 요구하는 것으로 플래그 처리하여 API가 요청을 거부했습니다. API는 이 거부 범주를reasoning_extraction으로 명명하며, 거부 메시지에는 다음 줄이 포함됩니다.
Details 줄이 포함되지 않았습니다.
해결 방법:
- Claude에게 사고나 추론을 그대로 또는 고정된 형식으로 작성하도록 요구하는 지시를 제거하거나 표현을 바꿉니다. 예를 들어
<thinking>섹션, 스크래치패드 섹션, JSON 출력의reasoning필드 등이 있습니다. 이러한 지시는 프롬프트에 있을 수도 있고, CLAUDE.md, 스킬, 서브에이전트 프롬프트, 출력 스타일, MCP 도구 설명처럼 Claude Code가 프롬프트와 함께 로드하는 사용자 지정 항목에 있을 수도 있습니다. - 사용자 지정 항목이 트리거인지 확인하려면 터미널에서
claude --safe-mode를 실행하여 사용자 지정 항목이 비활성화된 세션을 시작한 다음, 같은 프롬프트를 보냅니다 - 사용자 지정 항목을 변경한 후에는 새 세션을 시작합니다
- 이미 보낸 프롬프트의 표현을 바꾸려면 되감기 및 요약을 참조하십시오
- Claude에게 답변을 설명해 달라고 요청하는 것은 여전히 가능합니다. 간단한 설명, 결과의 근거, 또는 수행한 작업의 요약을 요청하십시오. Claude의 사고 요약을 읽으려면
showThinkingSummaries를 참조하십시오. - 더 많은 예시와 표현을 바꾼 요청이 여전히 거부되는 경우의 해결 방법은 추론을 thinking 블록에 유지하기를 참조하십시오
Output blocked by content filtering policy
API의 출력 콘텐츠 필터가 Claude가 생성하던 응답을 중단했습니다. 메시지 텍스트는 API에서 제공됩니다.- 마지막 메시지의 표현을 바꾸거나 다른 접근 방식을 사용합니다
- 차단을 트리거한 턴 이전의 체크포인트로 되돌아가려면 Esc를 두 번 누르거나
/rewind를 실행합니다. 체크포인트를 참조하십시오
명령줄 오류
이 오류는claude 명령줄과 그 하위 명령, 프롬프트에서 제출한 명령 이름, 그리고 /security-review처럼 프롬프트가 실행되기 전에 셸 명령을 실행해 컨텍스트를 수집하는 명령에서 발생합니다. CLI를 다시 실행하는 /tui에서도 발생합니다.
--bg와 --print 간의 충돌
이 메시지는 Claude Code v2.1.198 이상이 필요합니다. 같은 claude 호출에서 --bg를 -p 또는 --print와 함께 사용한 경우입니다. --bg는 나중에 claude agents로 연결하는 백그라운드 세션을 시작하는 반면, --print는 비대화형으로 실행되며 claude agents가 연결하는 대화형 세션을 시작하지 않습니다. v2.1.198 이전에는 이 조합이 연결할 수 없는 백그라운드 작업을 아무 알림 없이 생성했습니다.
-p또는--print를 제거합니다.--bg는 프롬프트를 위치 인수로 받으므로claude --bg "<task>"가 완전한 명령입니다. 셸에서 새 에이전트 디스패치하기를 참조하십시오.- 백그라운드 세션을 생성하는 대신 프롬프트를 비대화형으로 실행하고 결과를 출력하려면
--bg를 제거하고claude -p "<task>"를 실행합니다
Couldn’t tell whether --bg is a flag or text
Claude Code가 백그라운드 플래그로 의도한 것인지 텍스트로 의도한 것인지 구분할 수 없는 위치에 --bg 또는 --background를 넣어 claude를 실행한 경우입니다. 명령은 아무것도 시작하지 않고 다음 줄을 출력한 뒤 종료 코드 1로 종료되었습니다:
--background를 입력한 경우 이 줄에는 --background가 대신 표시됩니다.
해결 방법:
- 백그라운드 세션을 시작하려면 셸에서 플래그를 맨 앞에 두고 명령을 다시 실행합니다:
claude --bg --name nightly-audit "<task>"
시스템 프롬프트 플래그와 해당 파일 형식 간의 충돌
하나의claude 호출에서 --append-subagent-system-prompt를 --append-subagent-system-prompt-file과 함께 전달했기 때문에 claude가 세션을 시작하지 않고 종료 코드 1로 종료됩니다:
--system-prompt를 --system-prompt-file과 함께, 또는 --append-system-prompt를 --append-system-prompt-file과 함께 전달한 경우에도 claude가 같은 방식으로 종료되었습니다. 해당 쌍이 결합되지 않고 충돌했기 때문입니다. 해당 버전에서는 메시지에 함께 사용한 쌍의 이름이 표시됩니다.
해결 방법:
- 플래그의 한 가지 형식만 유지하고 다른 하나는 제거합니다. 고정된 프롬프트 파일과 실행별 텍스트를 결합하려면 두 플래그를 모두 전달하는 대신 실행 전에 텍스트를 파일에 병합합니다
Invalid --agents configuration
--agents에 전달한 값이 유효하지 않아 claude가 세션을 시작하지 않고 종료 코드 1로 종료됩니다. --safe-mode를 전달하거나 CLAUDE_CODE_SAFE_MODE를 설정하면 Claude Code는 --agents를 완전히 무시합니다. --resume 또는 --continue와 함께 사용하면 인라인 JSON 값은 검사되지 않고 세션이 시작되지만, 파일에서 읽은 값은 실행할 때마다 검사됩니다. v2.1.242 이전에는 Claude Code가 그래도 세션을 시작했습니다.
- 값이
{로 시작하지만 JSON으로 파싱되지 않거나--agents파일의 내용이 파싱되지 않으면, Claude Code는 JSON 파서 자체의 메시지를 담은invalid JSON:줄 하나를 출력합니다 - 파싱은 되지만 에이전트 정의가 CLI에서 정의한 서브에이전트의 스키마와 일치하지 않으면, Claude Code는 문제마다 한 줄씩 출력합니다
- 에이전트 이름이
-로 시작하면 Claude Code는<name>: agent names must not start with '-'를 출력합니다
…and N more로 대체합니다.
--print와 함께 사용하면 --agents는 인라인 객체 대신 JSON 파일 경로도 받습니다. v2.1.281 이전에는 --agents가 인라인 JSON만 받았고 파일 경로는 유효하지 않은 JSON으로 처리했습니다. 파일 형식에는 자체적인 거부 메시지가 있으며, 이 메시지 대신 출력됩니다. 다음과 같은 메시지가 포함됩니다:
Error: --agents takes a JSON object, or a file path only with --print (-p): Claude Code가 대화형 세션에서 값을 파일 경로로 읽었습니다. 정의를 인라인 JSON으로 전달하거나, 파일에서 읽으려면-p를 추가합니다.Error: --agents file not found: <path>: 해당 경로에 파일이 없습니다.{로 시작하지 않고 유효한 JSON도 아닌 값은 경로로 읽히므로, 셸이 훼손한 인라인 JSON도 이런 방식으로 실패할 수 있습니다. 경로나 따옴표 처리를 확인하고 명령을 다시 실행합니다.
- 메시지에 나열된 각 문제를 수정한 뒤 명령을 다시 실행합니다. CLI에서 정의한 서브에이전트가 받는 필드를 참조하십시오.
Cloud sessions cannot be created from a --restricted session
--restricted로 세션을 시작하면 Claude Code는 해당 세션에서 클라우드 세션을 생성하는 것을 거부합니다. 새 세션이 제한된 프로세스 밖에서 실행되어 제한 모드를 적용하지 않기 때문입니다. Claude Code는 서버에 연결하기 전에 클라이언트에서 거부하므로 클라우드 세션은 생성되지 않습니다:
- 제한된 세션에서 작업을 로컬로 실행합니다
- 세션이 시작되는 방식을 제어할 수 있다면
--restricted없이 새claude세션을 시작하고 그곳에서 클라우드 세션을 생성합니다
--restricted 플래그가 없었으며, 이전 버전에서는 알 수 없는 옵션 오류로 플래그 자체를 거부합니다.
Cloud sessions are disabled by your organization’s policy
조직의allow_remote_sessions 정책이 꺼져 있어 클라우드 세션과 이를 사용하는 명령을 사용할 수 없습니다:
/teleport, /remote-env, /web-setup처럼 클라우드 세션이 필요한 명령을 제출할 때 나타납니다. v2.1.268 이전에는 이러한 명령을 제출하면 대신 Unknown command가 반환되었습니다.
메시지가 대신 이 세션에서 사용 중인 자격 증명을 명시하고 Cloud sessions use your claude.ai login.으로 끝나는 경우 Cloud sessions use your claude.ai login을 참조하십시오. Claude Code가 조직의 정책을 전혀 불러오지 못한 경우에는 대신 다른 메시지가 표시됩니다.
해결 방법:
- 조직의 Owner에게 claude.ai/admin-settings/claude-code의 Claude Code 관리자 설정에서 클라우드 세션을 활성화하도록 요청합니다
Cloud sessions use your claude.ai login
정책 거부 메시지가 이 세션에서 사용 중인 자격 증명을 명시하고 이 문장으로 끝나는 경우, Claude Code는 해당 자격 증명을 발급한 조직의 클라우드 세션 정책을 확인한 것입니다. 이 조직은 claude.ai 로그인이 속한 조직과 다를 수 있습니다:--cloud 또는 --teleport 등을 사용해 셸에서 클라우드 세션을 시작하거나, 재개하거나, 메시지를 보낼 때 나타납니다. v2.1.296 이전에는 이 경우에도 Claude Code가 조직 관리자에게 문의하라는 형식을 출력했습니다.
Couldn’t verify your organization’s policy for cloud sessions
이 메시지들은 Claude Code가 조직의 정책을 불러오지 못했다는 의미입니다. Claude Code는 클라우드 세션을 생성하거나, 재개하거나, 메시지를 보내기 전에 이 정책을 확인합니다. 정책 요청이 아직 완료되지 않은 동안 표시되는 메시지는 다음과 같습니다:/teleport나 /web-setup처럼 클라우드 세션이 필요한 명령도 이 메시지를 표시합니다. 셸에서라면 Cloud sessions aren't available: 형식이 출력될 상황에서도 마찬가지이며, 두 번째 문장은 Check your network connection, then restart Claude Code and try again.으로 표시됩니다.
정책 요청이 실패한 후에는 메시지에 무엇이 실패했는지 표시됩니다. 이는 --cloud 또는 --teleport 같은 플래그로 셸에서 클라우드 세션을 시작하거나, 재개하거나, 메시지를 보낼 때 적용됩니다. API에 연결할 경로가 없으면 다음과 같이 표시됩니다:
ANTHROPIC_API_KEY 환경 변수처럼 이 세션이 claude.ai 로그인 대신 사용하는 자격 증명을 API가 받아들이지 않은 경우, 메시지에 해당 자격 증명이 명시되고 설정을 해제하라는 안내가 포함될 수도 있습니다:
Couldn't verify 메시지가 출력되었습니다.
해결 방법:
Couldn't verify메시지의 경우 네트워크 연결을 확인하고 다시 시도합니다. 세션 내에서는 먼저 Claude Code를 다시 시작합니다Cloud sessions aren't available:메시지의 경우 프록시를 확인하거나 메시지에 명시된 자격 증명의 설정을 해제하는 등 원인에 맞는 조치를 취한 뒤 명령을 다시 실행합니다
폴더가 추적 중인 파일을 대체하여 아무것도 stash되지 않음
이 메시지는 체크아웃에서 git이 추적하던 파일이나 링크가 있던 자리에 이제 폴더가 있다는 의미입니다. 예를 들어claude --teleport 또는 /teleport로 클라우드 세션을 터미널로 가져오는 중 stash 옵션을 선택한 후에 나타납니다. 이 상태를 stash하면 폴더 안의 파일이 삭제될 수 있으므로, Claude Code는 stash를 거부하고 체크아웃과 인덱스를 변경하지 않은 상태로 둡니다:
- 메시지 안내대로 변경 사항을 커밋하거나 폴더를 다른 곳으로 옮긴 뒤 teleport를 다시 실행합니다
--json-schema 값이 유효한 JSON Schema가 아님
비대화형 모드에서 --json-schema에 전달한 스키마가 JSON Schema 컴파일에 실패하여, claude가 프롬프트를 실행하지 않고 종료 코드 1로 종료됩니다. v2.1.205 이전에는 유효하지 않은 스키마가 오류 없이 구조화되지 않은 출력을 생성했으며, format 키워드를 사용하는 스키마는 모두 유효하지 않은 것으로 처리되었습니다.
"format": "email"처럼 format 키워드를 사용하는 스키마는 유효합니다. Claude Code는 format을 주석으로 받아들이며 이를 강제하지 않습니다.
Claude Code는 스키마 컴파일 전에 두 가지 검사를 실행합니다. 파싱할 수 없는 JSON 값은 Error: --json-schema is not valid JSON으로, 객체가 아닌 유효한 JSON은 Error: --json-schema must be a JSON object로 거부합니다.
해결 방법:
- 진단 메시지가 명시한 스키마 부분을 수정한 뒤 명령을 다시 실행합니다
- 동작하는 스키마와 명령은 구조화된 출력 얻기를 참조하십시오
Settings file exceeds the 2MiB limit
--settings에 전달한 파일이 2 MiB보다 커서 claude가 파일을 불러오지 않고 시작 시 종료 코드 1로 종료됩니다. v2.1.214 이전에는 Claude Code가 크기 검사 없이 파일을 읽었으며, 수 기가바이트 크기의 파일이나 /dev/zero 같은 장치 파일로 인해 메모리가 무한정 증가했습니다.
--settings 경로도 같은 방식으로 거부합니다. 장치, FIFO 또는 소켓은 Error: Cannot use settings file (Not a regular file (device, FIFO, or socket)) 뒤에 경로를 표시하며, 디렉터리는 EISDIR 사유를 표시합니다.
해결 방법:
--settings가 2 MiB 미만의 일반 JSON 설정 파일을 가리키도록 합니다. 형식은 설정을 참조하십시오.
Configuration error in ~/.claude.json
Claude Code가 계정 정보, MCP 서버, 프로젝트별 상태를 보관하는 파일인~/.claude.json을 파싱하지 못했습니다. claude -p 같은 비대화형 시작은 종료 코드 1로 종료됩니다.
Claude Code가 백업을 찾으면 출력에 해당 백업이 명시되고, 백업을 다시 복사하는 cp 줄이 출력됩니다:
- 출력에
cp줄이 있는 경우: 터미널에서 해당 줄을 실행합니다. Windows에서는 PowerShell에서 실행합니다. - 출력에
cp줄이 없거나, 실행한 후에도 오류가 다시 나타나는 경우:~/.claude.json에 구성이 아직 남아 있다면 JSON을 수정합니다. 수정할 수 없다면~/.claude/backups/의 다른.claude.json.backup.<timestamp>파일(있는 경우)을 복사해 설정 파일을 덮어쓰거나, 설정 파일의 이름을 변경합니다.~/.claude.json파일이 없으면 Claude Code는 파일에 있던 내용 없이 기본 설정으로 시작합니다. ~/.claude.json에 더 이상 구성이 없는 경우:~/.claude/backups/또는 홈 디렉터리에서 구성이 아직 남아 있는.claude.json.corrupted.<timestamp>파일을 찾습니다. 해당 파일의 JSON을 수정한 뒤~/.claude.json위에 복사합니다. 그런 파일을 찾거나 수정할 수 없다면 구성이 남아 있는.claude.json.backup.<timestamp>파일로 같은 단계를 시도합니다. 그런 파일도 없다면~/.claude.json의 이름을 변경하고claude mcp add로 MCP 서버를 다시 추가합니다.
Claude configuration file was empty and no backup holds anything
시작 시 이 메시지가 표시되면 메시지에 명시된 파일이 비어 있었고, 해당 파일의.backup 사본 중 어느 것에도 내용이 없다는 의미입니다. Claude Code는 해당 파일이 보관하는 내용에 대해 기본값으로 시작했습니다. settings.json 파일과 .mcp.json은 별도의 파일입니다.
- 해당 파일에 구성해 두었던 내용을 다시 설정합니다. 예를 들어 터미널에서
claude mcp add로user및local범위의 MCP 서버를 추가합니다. - Claude Code가 요청하면 다시 로그인합니다
The current directory no longer exists
셸이 진입한 후 삭제되거나 이동된 디렉터리(예: 다른 셸이 제거한 worktree나 임시 디렉터리)에서claude를 시작한 경우입니다. Claude Code는 작업 디렉터리를 읽을 수 없으므로, 대화형 모드와 비대화형 모드 모두에서 세션을 시작하기 전에 종료 코드 1로 종료됩니다. v2.1.239 이전에는 Claude Code가 이 메시지 대신 축소된 번들 소스와 원시 ENOENT ... uv_cwd 스택을 stderr에 출력하며 비정상 종료되었습니다.
Can't read the current directory (EACCES). Start Claude Code from a different directory.
macOS에서 ~/Desktop, ~/Documents, ~/Downloads 또는 iCloud Drive의 디렉터리에 대해 EPERM이 표시되면 대개 macOS가 터미널 앱의 해당 폴더 접근을 차단하고 있다는 의미입니다. 해당 폴더를 읽는 다른 명령도 같은 방식으로 실패합니다. 그 위치에서 ls를 실행하면 sudo를 사용하더라도 Operation not permitted가 보고됩니다.
해결 방법:
- 홈 디렉터리나 프로젝트 디렉터리처럼 존재하는 디렉터리로 이동한 뒤
claude를 다시 실행합니다 - 디렉터리가 같은 경로에 다시 생성된 경우 셸은 여전히 삭제된 디렉터리를 붙잡고 있습니다.
cd "$PWD"를 실행하거나 디렉터리에서 나갔다가 다시 들어간 뒤claude를 다시 실행합니다 - macOS에서
EPERM이 표시되는 경우 Cmd+Q로 터미널 앱을 종료하고 다시 연 뒤 해당 폴더로 돌아가claude를 실행합니다. 해당 폴더에서ls가 여전히 실패하면 시스템 설정 > 개인정보 보호 및 보안 > 파일 및 폴더를 열고 터미널 앱에 대해 해당 폴더를 켠 뒤 터미널을 다시 엽니다
임시 디렉터리가 거부되었거나 생성할 수 없음
macOS와 Linux에서 Claude Code는 시작 시 시스템 임시 디렉터리 또는CLAUDE_CODE_TMPDIR 재정의 아래에 전용 임시 디렉터리 claude-<uid>를 생성합니다. 디렉터리를 생성할 수 없거나, 해당 경로에 이미 있는 항목이 안전 검사를 통과하지 못하면 Claude Code는 실패 내용을 stderr에 출력하고 세션을 시작하지 않고 종료 코드 1로 종료됩니다:
could not be created뒤에is full (ENOSPC)가 표시되는 경우 메시지에 명시된 볼륨의 디스크 공간을 확보합니다. 대신your disk quota on the volume holding /tmp is used up (EDQUOT)가 표시되는 경우 해당 볼륨에서 더 이상 필요하지 않은 본인 파일을 삭제합니다Refusing to use it형식의 경우 링크가 가리키는 대상이 아니라 명시된 항목 자체를 제거한 뒤 Claude Code를 다시 시작합니다.owned by uid형식의 경우 관리자나 해당 사용자만 그 항목을 제거할 수 있습니다is not readable의 경우 명시된 디렉터리에chmod 0700을 실행하거나, 디렉터리를 제거하고 다시 시작합니다- 어느 경우에도
CLAUDE_CODE_TMPDIR를 사용자가 제어하는 디렉터리로 설정하고 Claude Code를 다시 시작할 수 있으며, 거부된 경로는 그대로 둡니다
ENOSPC: no space left on device, mkdir '/tmp/claude-501'이 출력되며, 해결 단계는 동일합니다.
디스크가 가득 차서 Claude Code가 저장하지 못함
claude -p 실행 후 stderr에 이 줄이 표시되면 디스크가 가득 찼거나 디스크 할당량을 모두 사용하여 Claude Code가 실행 내용을 모두 저장하지 못했다는 의미입니다:
json 출력에서는 실행이 종료 코드 1로 종료되며, 응답은 이미 출력된 상태입니다. stream-json 출력에서는 실행이 평소의 종료 코드를 유지하며, 응답도 여전히 전달됩니다.
해결 방법:
the disk is full (ENOSPC): 다음 실행 전에 메시지의 경로가 있는 디스크의 공간을 확보합니다your disk quota is used up (EDQUOT): 다음 실행 전에 공간을 확보하거나 더 큰 할당량을 요청합니다
디렉터리를 실제 위치로 확인할 수 없음
작업 디렉터리의 하위 디렉터리에 대해/add-dir을 실행했는데, Claude Code가 해당 디렉터리를 실제 위치로 확인하지 못한 경우입니다.
작업 디렉터리의 하위 디렉터리에는 이미 파일 접근 권한이 있으므로 /add-dir은 해당 디렉터리의 스킬, 명령, 에이전트만 불러옵니다. Claude Code는 이를 불러오기 전에 심볼릭 링크를 모두 확인한 디렉터리의 실제 위치가 작업 디렉터리 안에 있는지 검사합니다. Claude Code가 그 위치를 확인할 수 없으면 아무것도 불러오지 않고 다음 메시지를 표시합니다:
- 경로가 작업 디렉터리 안의 실제 디렉터리를 가리키는지 확인한 뒤
/add-dir을 다시 실행합니다 - 이 메시지는 파일 접근 권한을 변경하지 않으며, 해당 디렉터리의
.claude/콘텐츠가 불러와지지 않았음을 알릴 뿐입니다
/net/<host> 자동 마운트에 있을 때 모든 /add-dir <subdirectory>에 대해서도 이 메시지가 나타났습니다. 이 경우 Claude Code는 설계상 경로 확인을 하지 않으며, 디렉터리에는 문제가 없었고 재시도해도 소용이 없었습니다.
Remote Control 시작 시 워크스페이스가 신뢰되지 않음
claude ultrareview가 Error: Workspace not trusted를 출력한 경우에는 대신 claude ultrareview 실행 시 워크스페이스가 신뢰되지 않음을 참조하십시오.claude remote-control 또는 그 별칭인 claude rc로 Remote Control 서버 모드를 시작했는데, 명령이 해당 디렉터리를 신뢰할지 물을 수 없었던 경우입니다. 예를 들어 명령의 표준 입력이나 표준 출력 중 하나가 리디렉션되거나 파이프로 연결되어 터미널이 아닌 경우입니다. 명령은 종료 코드 1로 종료됩니다:
Error: Workspace not trusted.로 시작하는 두 가지 변형은 디렉터리를 신뢰할 때 켜지는 항목을 표시하기에 터미널이 너무 작거나, 터미널이 크기를 보고하지 않을 때 나타납니다. 창을 키우거나 일반 터미널 창으로 전환한 뒤 claude rc를 다시 실행합니다.
홈 디렉터리에서는 메시지가 다릅니다. 워크스페이스 신뢰 대화 상자는 홈 디렉터리에 대한 신뢰를 절대 저장하지 않으므로, 그곳에서 수락해도 이 검사를 통과할 수 없기 때문입니다. v2.1.214 이전에는 홈 디렉터리에서 위의 메시지가 표시되었으며, 그 안내는 그곳에서 성공할 수 없었습니다.
Trust <directory>? 질문에 n으로 답하거나 Enter를 누르면 명령은 디렉터리를 명시하는 Remote Control did not start 메시지를 출력하고 종료 코드 1로 종료됩니다. y로 답하려면 claude rc를 다시 실행합니다.
해결 방법:
- 먼저 터미널에서 디렉터리를 신뢰합니다. 그곳에서
claude를 실행하고 워크스페이스 신뢰 대화 상자를 수락한 다음 원래 명령을 다시 실행합니다 - 홈 디렉터리에 있는 경우 프로젝트 디렉터리로 이동하여 그곳에서 Remote Control을 시작합니다
claude ultrareview 실행 시 워크스페이스가 신뢰되지 않음
신뢰하지 않은 폴더에서claude ultrareview가 해당 폴더를 신뢰하는지 물을 수 없으면, 리뷰가 시작되기 전에 실행이 종료 코드 1로 종료됩니다:
claude ultrareview --json > findings.json처럼 출력을 파일로 보내면 표준 출력이 터미널이 아니게 됩니다.
해결 방법:
- 스크립트나 CI 작업에서는
--trust-workspace를 덧붙여 해당 실행에 대해 폴더를 신뢰합니다:claude ultrareview --trust-workspace. 이 플래그를 덧붙이면 git과 Claude Code가 폴더의 git 구성과 프로젝트 설정에 지정된 프로그램을 실행할 수 있으므로, 신뢰하는 코드에 대해서만 덧붙입니다. 코드를 신뢰하지 않는 풀 리퀘스트의 경우 신뢰하는 브랜치에서 리뷰를 실행합니다. - 본인의 컴퓨터에서는 해당 폴더에서
claude를 실행하고 워크스페이스 신뢰 대화 상자를 수락한 뒤 원래 명령을 다시 실행합니다
/ultrareview와 /code-review ultra는 Ultrareview did not start: "<folder>" is not trusted, and this session started without asking whether you trust it와 함께 중단될 수 있습니다. IS_DEMO를 설정하지 않은 상태로 해당 폴더에서 claude를 시작하고, 워크스페이스 신뢰 대화 상자를 수락한 다음 새 세션에서 명령을 실행합니다.
claude ultrareview의 다음 메시지는 모두 리뷰가 시작되지 않았고 종료 코드가 1이라는 의미입니다.
Error: Workspace not trusted. This terminal ...: 터미널이 행과 열 수를 보고하지 않았거나, 신뢰 질문과 경고를 표시할 공간이 부족합니다. 터미널을 키우거나 크기를 보고하는 터미널을 사용한 뒤claude ultrareview를 다시 실행합니다. 홈 디렉터리 밖에서는 해당 폴더에서claude를 한 번 실행하고 신뢰 대화 상자를 수락하여 이후 그곳에서의 실행에서 묻지 않도록 할 수도 있습니다.Error: Workspace not trusted. <folder> is your home directory: 홈 디렉터리에 대한 신뢰는 절대 저장되지 않으므로, 그곳에서 먼저claude를 실행해도 소용이 없습니다. 대신 프로젝트 디렉터리에서claude를 한 번 실행해 신뢰 대화 상자를 수락한 뒤 그곳에서claude ultrareview를 실행하거나,--trust-workspace를 덧붙입니다.No answer in time.뒤에Error: Workspace not trusted:Trust <folder>? [y/N]질문에 5분 동안 답이 없었습니다.claude ultrareview를 다시 실행하고 질문에 답합니다.Ultrareview did not start: <folder> is not trusted: 예를 들어n으로 답하거나 Enter를 눌러Trust <folder>? [y/N]질문에서 거절했습니다. 리뷰를 시작하려면claude ultrareview를 다시 실행하고y로 답합니다.Ultrareview did not start: `--trust-workspace` takes no value: PR 번호나false처럼 플래그가 아닌 것이--trust-workspace뒤에 왔습니다. 폴더를 신뢰하지 않는다면 플래그를 빼십시오. 이번 실행에 대해 신뢰하려면 PR 번호나 기준 브랜치를 플래그 앞에 둡니다:claude ultrareview 1234 --trust-workspace.
claude ultrareview가 --trust-workspace를 받지 않았습니다.
질문에 답이 없어 Remote Control이 시작되지 않음
이 메시지는claude remote-control이 메시지에 인용된 최초 실행 질문을 했지만 답을 받지 못했다는 의미입니다:
Enable Remote Control?: 스크립트나 서비스에서는 누군가 답하기 전에 표준 입력이 끝납니다. 스크립트나 서비스가 실행되는 사용자로 터미널에서claude remote-control을 한 번 실행하고y로 답합니다.Choose [1/2] (default: 1)::claude remote-control을 다시 실행하고 스폰 모드를 선택하거나,--spawn=same-dir또는--spawn=worktree를 전달하여 질문을 건너뜁니다
Remote Control이 시작하는 세션에 전달되지 않음
remote-control 동사 앞에 전역 claude 플래그를 넣어 Remote Control을 시작한 경우입니다. 이 플래그는 --settings, --setting-sources, --permission-mode, --disallowed-tools, --mcp-config처럼 Remote Control이 시작하는 세션을 제한하거나 구성하는 플래그입니다. 동사 앞에 둔 플래그는 해당 세션에 전달되지 않습니다. 대신 Claude Code는 플래그를 명시하며 시작을 거부합니다:
--verbose, --model, 또는 래퍼가 삽입한 --session-id나 --plugin-dir처럼 제거해도 무해한 전역 플래그는 거부하지 않습니다. 이러한 플래그는 무시되며 Remote Control이 시작됩니다.
Claude Code는 아직 무해하다고 인식하지 못한 전역 플래그에 대해서도 시작을 거부하므로, 최신 릴리스에서 추가된 플래그는 이후 릴리스에서 무해한 것으로 표시될 때까지 이 메시지에 나타날 수 있습니다.
해결 방법:
- 동사 앞에서 플래그를 제거하고 Remote Control 자체 옵션을 동사 뒤에 전달합니다.
claude remote-control --help에서 옵션 목록을 확인할 수 있습니다 - 거부된 플래그가
--permission-mode인 경우claude remote-control --permission-mode <mode>를 실행하여 Remote Control이 시작하는 세션의 권한 모드를 설정합니다
claude remote-control이 자체 플래그를 받지 않았으며, 명령이 unknown option 오류로 실패했습니다.
--settings 파일 때문에 Remote Control이 시작되지 않음
claude remote-control --settings에 전달한 파일에 문제가 있습니다:
- 메시지가 명시한 문제를 수정한 뒤
claude remote-control명령을 다시 실행합니다
The settings file has changed since Remote Control started
claude remote-control을 실행 중인 터미널에 이 메시지가 표시되면 --settings에 전달한 파일의 현재 상태로는 세션이 시작되지 않는다는 의미입니다:
- 파일을 현재 상태로 사용하려면
claude remote-control을 중지하고 같은 명령을 다시 실행합니다. 서버가 제공하던 세션을 다시 불러오려면 서버 중지 후 세션 재개하기를 참조하십시오. - Remote Control이 시작할 때의 설정을 유지하려면 파일 내용을 원래대로 되돌린 뒤,
claude remote-control이 종료된 경우 명령을 다시 실행합니다
--sandbox or --no-sandbox is not supported by claude remote-control
이 오류는 Remote Control 서버를 시작하는 명령이 remote-control 뒤에 --sandbox 또는 --no-sandbox를 전달하는데, claude remote-control은 두 플래그 모두 받지 않는다는 의미입니다. 서버는 시작되지 않고 종료 코드 1로 종료됩니다:
- 서버를 대신 시작하는 스크립트나 서비스 정의를 포함하여 명령에서 플래그를 제거한 뒤 다시 실행합니다
- 서버가 시작하는 세션을 샌드박스에서 실행하려면 설정 파일에서
sandbox.enabled를true로 설정하여 샌드박싱을 켭니다
claude remote-control에서 제거되었으므로, 이전 버전용으로 작성된 명령에는 여전히 둘 중 하나가 포함되어 있을 수 있습니다.
claude import is not yet available in this build
claude import를 실행했는데 Claude Code가 가져오기 흐름이 꺼져 있음을 확인하여, 명령이 가져오기를 시작하지 않고 종료 코드 1로 종료됩니다. v2.1.222 이전에는 가져오기 흐름이 꺼진 빌드에서 import를 프롬프트로 처리하여 이 메시지를 출력하는 대신 대화형 세션을 시작했습니다.
claude import를 켭니다. 이 메시지는 캐시된 값이 꺼져 있다는 의미입니다. 원인은 대개 다음 중 하나입니다:
- 설치 후 아직 세션을 시작하지 않아 Claude Code가 플래그를 가져오지 않았습니다. 기능을 사용할 수 있는 경우에도 첫
claude import에서 이 메시지가 출력될 수 있습니다. - Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, Claude Platform on AWS를 통해서나 Claude apps gateway를 통해 Claude Code를 사용하고 있습니다. 이러한 세션에서는 Claude Code가 기능 플래그를 가져오지 않으므로
claude import를 계속 사용할 수 없습니다. - 기능 플래그 가져오기를 끄는
DISABLE_TELEMETRY,DO_NOT_TRACK,CLAUDE_CODE_DISABLE_FEATURE_FLAGS,DISABLE_GROWTHBOOK, 또는CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC를 설정했으므로claude import를 계속 사용할 수 없습니다.
- 새로 설치한 경우
claude를 시작하고 세션이 로드될 때까지 기다린 뒤 종료하고claude import를 다시 실행합니다 - 기능 플래그 가져오기가 계속 꺼져 있는 환경에서는 구성을 직접 설정합니다.
claude mcp add로 MCP 서버를 추가하고, 옮겨 오려는CLAUDE.md파일, 스킬과 명령, 서브에이전트를 생성합니다. 메시지에는~/.claude/settings.json도 언급됩니다.claude import가 옮기는 구성 중 이 파일에는 권한 모드만 들어 있으며, Claude Code는 이 파일에서 MCP 서버를 읽지 않습니다.
Could not read Claude Code config
Claude Code가 계정 정보와 프로젝트별 상태를 저장하는 파일인~/.claude.json을 파싱하지 못하는 상태에서 claude import를 실행한 경우입니다. 이 하위 명령은 사용 가능 여부를 확인하기 위해 해당 파일을 읽지만, 대화형 세션이 표시하는 복구 대화 상자를 표시하지 않으므로 종료 코드 1로 종료됩니다. v2.1.222 이전에는 읽을 수 없는 설정 파일이 있을 때 claude import가 대화형 세션을 시작했으며, 그 세션의 복구 대화 상자가 파일을 처리했습니다.
- 인수 없이
claude를 실행합니다. Claude Code가 유효하지 않은 파일을 감지하고 초기화를 제안합니다. 그런 다음claude import를 다시 실행합니다. - 직접 편집한 내용을 유지하려면 대신 편집기에서
~/.claude.json의 JSON 구문을 수정한 뒤claude import를 다시 실행합니다
Claude Desktop에서 서버를 가져올 수 없음
Claude Code가claude mcp add-from-claude-desktop에서 선택한 서버 중 하나를 추가하지 못했습니다. 명령은 선택한 다른 서버는 계속 가져오며, 추가하지 못한 서버마다 한 줄씩 출력합니다. v2.1.205 이전에는 처음 실패한 서버에서 가져오기가 중단되었습니다.
claude mcp는 문자, 숫자, 하이픈, 밑줄로 제한합니다. 다른 사유로는 검증에 실패한 서버 구성, 그리고 조직의 MCP 정책에 의해 차단된 서버가 있습니다.
해결 방법:
claude_desktop_config.json에서 서버 이름을 문자, 숫자, 하이픈, 밑줄만 사용하도록 변경한 뒤claude mcp add-from-claude-desktop을 다시 실행합니다- 유효한 이름으로
claude mcp add또는claude mcp add-json을 사용해 해당 서버를 직접 추가합니다. Claude Desktop에서 MCP 서버 가져오기를 참조하십시오.
managed 범위에 MCP 서버를 추가할 수 없음
--scope managed로 claude mcp add 또는 claude mcp add-json을 실행한 경우입니다. 이 범위에는 조직이 managedMcpServers 관리형 설정을 통해 제공하는 서버가 들어 있습니다. Claude Code는 이 서버들을 관리형 설정에서만 읽으므로, 명령으로 해당 범위에 서버를 기록할 수 없습니다.
- 기록할 수 있는 범위인
local,user,project에 서버를 추가합니다.--scope없이 실행하면 명령은local을 사용합니다. MCP 설치 범위를 참조하십시오 - 조직의 모든 사용자에게 서버를 제공하려면 배포하는 관리형 설정의
managedMcpServers에 서버를 추가합니다
관리형 설정이 플러그인 서버만 허용할 때 MCP 서버를 추가할 수 없음
조직의 관리형 설정이strictPluginOnlyCustomization을 true 또는 mcp를 포함하는 목록으로 설정한 상태에서 claude mcp add 또는 claude mcp add-json을 실행한 경우입니다. 이 설정에서는 Claude Code가 ~/.claude.json이나 .mcp.json에서 MCP 서버를 불러오지 않으므로, 명령은 절대 로드되지 않을 서버를 저장하는 대신 종료 코드 1로 종료됩니다:
claude mcp add-from-claude-desktop은 선택한 각 서버를 가져오지 않은 것으로 보고하며, 이 메시지를 사유로 표시합니다. /import는 추가하려는 각 MCP 서버에 대해 이 메시지를 보고하며, 발견한 다른 항목은 계속 가져옵니다.
v2.1.284 이전에는 이러한 명령이 서버를 저장하고 성공을 보고했지만, 서버는 절대 로드되지 않았습니다.
해결 방법:
- 서버를 제공하는 플러그인을 설치합니다
- 관리자에게 플러그인으로 서버를 배포하거나, 원격 HTTP 또는 SSE 서버인 경우
managedMcpServers를 통해 제공하도록 요청합니다
Can’t read .mcp.json
--scope project를 사용한 claude mcp add나 claude mcp add-json, 또는 claude mcp remove처럼 프로젝트의 .mcp.json을 읽는 명령이 현재 디렉터리의 파일이 일반 파일이 아니거나 2 MiB보다 크다는 것을 발견하여, 파일을 읽지 않고 이 오류와 함께 종료됩니다.
.mcp.json 위치에 FIFO가 있으면 명령이 출력 없이 무한정 대기했으며, /dev/zero 같은 장치 파일에 대한 심볼릭 링크가 있으면 프로세스가 강제 종료될 때까지 메모리가 증가했습니다.
해결 방법:
- 현재 디렉터리의
.mcp.json위치에 무엇이 있는지 확인합니다. 이를 프로젝트 범위 형식의 일반 JSON 파일로 교체하거나 삭제한 뒤 명령을 다시 실행합니다.
MCP 서버가 저장되거나 제거되지 않음
이 오류는claude mcp add 또는 claude mcp remove 같은 명령이 변경 사항을 ~/.claude.json에 반영하지 못했다는 의미입니다. 다른 Claude Code 프로세스가 파일을 잠근 상태로 유지했거나, 파일이 읽기 전용이거나 샌드박스로 보호되어 있을 수 있습니다.
was not saved to 대신 was not removed from으로, add the server again 대신 remove the server again으로 표시됩니다. local 범위 서버의 경우 경로 뒤에 해당 항목이 속한 프로젝트 디렉터리가 (local scope for /path/to/project) 형태로 표시됩니다.
해결 방법:
- 다른 Claude Code 프로세스가 실행 중인 경우: 명령은 파일 잠금을 약 10~20초 동안 기다린 뒤 기록하지 않고 포기합니다.
CLAUDE_CODE_CONFIG_LOCK_WAIT_MS를60000처럼 밀리초 단위의 더 긴 대기 시간으로 설정하고 같은 명령을 다시 실행합니다. - 파일이 읽기 전용이거나 샌드박스로 보호된 경우: 메시지가 명시한 파일을 쓰기 가능하게 만들고 같은 추가 또는 제거 명령을 다시 실행하거나, 해당 명령을 샌드박스 밖에서 실행합니다.
claude mcp add, claude mcp add-json, claude mcp remove가 성공을 보고했습니다. v2.1.318 이전에는 메시지에 잠금에 대한 언급이 없었으며, Claude Code가 CLAUDE_CODE_CONFIG_LOCK_WAIT_MS를 읽지 않았습니다.
MCP 서버가 저장되거나 제거되지 않았을 수 있음
user 또는 local 범위의 서버에 대해 claude mcp add, claude mcp add-json, 또는 claude mcp remove를 실행했는데, Claude Code가 변경 사항을 확인하기 위해 ~/.claude.json을 다시 읽지 못한 경우입니다. 변경 사항이 디스크에 반영되었을 수도 있고 아닐 수도 있습니다. to confirm the change 뒤의 괄호 안에 사유가 표시됩니다.
may not have been removed로 표시되고 then remove the server again if it is still listed로 끝납니다. 사유가 the file was not found인 경우 서버가 여전히 구성되어 있을 수 있습니다.
v2.1.283 이전에는 변경 사항을 확인할 수 없는 경우에도 명령이 성공을 보고했습니다.
해결 방법:
claude mcp get <name>을 실행하여 변경 사항이 디스크에 반영되었는지 확인합니다.local범위 서버의 경우 로컬 범위는 프로젝트별이므로 서버가 속한 프로젝트 디렉터리에서 실행합니다.- 추가 후 서버가 없거나 제거 후에도 여전히 목록에 있으면 같은 추가 또는 제거 명령을 다시 실행합니다.
Server is Anthropic-hosted and doesn’t support local OAuth
URL이 서드파티 ID 공급자를 통해 인증하는 Anthropic 호스팅 커넥터 호스트를 가리키는 MCP 서버에 대해 로그인을 시작한 경우입니다. 이러한 호스트에는microsoft365.mcp.claude.com, gmail.mcp.claude.com, gcal.mcp.claude.com이 포함됩니다. 이 호스트들의 로그인은 claude.ai를 통해서만 동작하므로, Claude Code는 /mcp 패널과 claude mcp login 모두에서 이 호스트들에 대한 로컬 OAuth 흐름 시작을 거부합니다.
- 같은 URL의 claude.ai 커넥터를 가리지 않도록
claude mcp remove <name>으로 항목을 제거합니다 - 제거한 후 Claude Code에서 사용하는 계정으로 로그인한 상태에서 claude.ai/customize/connectors에서 서비스를 연결합니다. 연결되면 현재 인증 방식이 claude.ai 구독 로그인인 경우 커넥터가 Claude Code에 자동으로 나타납니다
Server rejected the Authorization header minted by the configured headersHelper
headersHelper가 Authorization 헤더를 제공하는 MCP 서버가 연결에 HTTP 401 또는 403으로 응답하여, Claude Code가 연결을 실패로 보고합니다. 헬퍼가 Authorization 헤더를 제공하므로 Claude Code는 해당 서버에 대해 OAuth로 폴백하지 않습니다:
- Claude Code가 실행하는 방식 그대로
headersHelper명령을 직접 실행합니다. Claude Code가 실행하는 디렉터리에서, Claude Code가 설정하는 환경 변수와 함께, 그리고 프로젝트.mcp.json, 플러그인 또는 프로젝트 에이전트 파일에서 온 서버의 경우 Claude Code가 제거하는 자격 증명 변수 없이 실행합니다. 서버의 엔드포인트가 받아들이는Authorization값을 출력하는지 확인합니다 - 헬퍼나 자격 증명 소스를 수정한 후
/mcp에서 서버를 선택하고 Reconnect를 선택합니다
Authorization 헤더를 제공하는 서버에 대해서도 Claude Code가 OAuth 검색을 실행했습니다. 이 검색은 거부된 자격 증명을 보고하는 대신 Incompatible auth server: does not support dynamic client registration으로 실패할 수 있었습니다.
MCP 서버가 elicitation 기능을 거부함
Java MCP SDK 0.11.0부터 0.17.0 사이 버전으로 만든 MCP 서버가 연결을 거부했습니다. 해당 SDK 버전은 Claude Code가 핸드셰이크에서 선언하는form 및 url elicitation 모드를 파싱할 수 없습니다. 메시지는 다음과 같습니다:
- 서버를 Java MCP SDK 0.17.1 이상, 또는 메시지에 명시된 Spring AI 릴리스 중 하나로 업그레이드합니다
- 또는 MCP 구성에서 해당 서버 항목에
"bareElicitationCapability": true를 추가한 뒤 Claude Code를 다시 시작합니다. 이 필드는 stdio,sse,http,ws항목에서 허용되며 Claude Code v2.1.281 이상이 필요합니다
.mcp.json 항목은 하나의 HTTP 서버에 대해 이 필드를 설정합니다:
/mcp에 서버가 연결된 것으로 표시됩니다. Claude Code는 해당 서버에만 form 모드를 선언하므로, 서버를 업그레이드한 후에는 이 필드를 제거합니다.
서버가 Unrecognized field "form"을 포함하는 오류처럼 자체 오류 텍스트와 함께 실패할 수도 있습니다. 같은 해결 방법이 적용됩니다.
MCP 권한 프롬프트 도구를 찾을 수 없음
실행에서 처음으로 권한 결정이 필요했을 때--permission-prompt-tool에 전달한 도구가 연결된 MCP 도구 중에 없었습니다. 서버가 연결되지 않았거나, 연결된 서버 중 해당 이름의 도구를 노출하는 서버가 없기 때문입니다. Claude Code는 그래도 프롬프트를 전송합니다. 비대화형 실행은 첫 도구 호출에서 이 오류와 함께 종료 코드 1로 종료되므로, 요청은 이루어졌지만 응답은 생성되지 않습니다. 첫 프롬프트 전에 Claude Code는 MCP_TIMEOUT으로 설정된 서버별 연결 타임아웃인 30초까지 해당 서버가 연결되기를 기다립니다. v2.1.206 이전에는 시작 시 서버 연결 완료를 기다리지 않았으므로, 느리게 시작하지만 정상인 서버에서도 이 오류가 발생했습니다.
Available MCP tools: 뒤의 목록에는 연결되었던 MCP 도구가 표시됩니다.
해결 방법:
- 서버가 시작되고 연결 상태를 유지하는지 확인합니다. 같은 디렉터리에서
claude mcp list를 실행하고 서버가 연결된 것으로 표시되는지 확인합니다 - 도구 이름이 서버가 노출하는
mcp__<server>__<tool>이름과 일치하는지 확인합니다 - 서버가 시작하는 데 30초보다 오래 걸리면
MCP_TIMEOUT을 늘립니다
OAuth callback port is already in use
OAuth로 원격 MCP 서버에 로그인하면 Claude Code는 로그인 콜백을 받기 위해 로컬 리스너를 시작합니다. 해당 리스너에 필요한 포트를 다른 프로세스가 점유하고 있으면 로그인이 이 메시지와 함께 실패합니다. 이는 주로MCP_OAUTH_CALLBACK_PORT 변수나 --callback-port로 설정한 고정 콜백 포트에서 발생합니다. 고정 포트가 없으면 Claude Code가 사용 가능한 포트를 선택하기 때문입니다.
netstat -ano | findstr :<port> 명령이 제안됩니다.
해결 방법:
- 메시지의 명령을 실행하여 포트를 점유한 프로세스를 찾고, 해당 프로세스를 중지하거나 종료될 때까지 기다립니다
- 다른 프로그램이 해당 포트를 계속 필요로 한다면 서버에 다른 리디렉션 URI를 등록하고, 사용하는 방식에 따라
MCP_OAUTH_CALLBACK_PORT또는--callback-port로 해당 포트를 설정합니다 - 그런 다음 예를 들어
/mcp에서 서버를 선택하여 로그인을 다시 시작합니다
No available ports for OAuth redirect
OAuth로 원격 MCP 서버에 로그인하면 Claude Code는 로그인 콜백을 받기 위해 로컬 리스너를 시작합니다. Claude Code가 이를 위한 로컬 포트를 바인딩할 수 없으면 로그인이 이 메시지와 함께 실패합니다. 예를 들어 로컬 리스너를 거부하는 보안 소프트웨어나 샌드박스 정책처럼, 컴퓨터의 무언가가127.0.0.1에서의 수신을 막고 있습니다.
- 보안 소프트웨어나 샌드박스 정책이 프로세스의
127.0.0.1수신을 차단하는지 확인하고, Claude Code가 로컬 포트를 바인딩할 수 있도록 허용합니다 - 그런 다음 예를 들어
/mcp에서 서버를 선택하여 로그인을 다시 시작합니다
origin/HEAD 없이 /security-review 실패
/security-review는 origin 원격의 기본 브랜치를 기록하는 로컬 ref인 origin/HEAD와 현재 브랜치를 비교하는 diff로 리뷰 컨텍스트를 구성합니다. 해당 ref가 없으면 diff를 수집하는 git 명령이 실패하고, 리뷰는 시작되기 전에 중단됩니다.
git log나 다른 git diff가 인용될 수 있습니다. Git은 원격이 기본 브랜치를 알리고 fetch refspec이 이를 포함하는 경우에만 origin/HEAD를 생성하며, 커밋이 있는 원격을 전체 git clone하면 이 조건이 충족됩니다. 다음과 같은 설정에서는 ref가 없습니다:
- 너무 좁은 refspec을 가져오는 단일 브랜치 또는 CI 체크아웃
- 서버 측 HEAD가 아무도 푸시하지 않은 브랜치를 가리키는 원격
origin원격이 없거나 한 번도 fetch하지 않은 저장소
Shell command permission check failed for pattern "...": 명령의 권한 검사에서 허용되지 않았습니다. 각 권한 모드에서 어떤 결과가 중단을 일으키는지, 그리고allowed-tools가 언제 명령을 사전 승인하는지는 주입된 명령에 대한 권한 검사를 참조하십시오Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found: 스킬의 frontmatter가 bash가 없는 컴퓨터에서 bash를 요구합니다. Git for Windows를 설치하거나 frontmatter를shell: powershell로 변경합니다. 주입된 명령이 실행되는 방식을 참조하십시오
- 원격의 기본 브랜치를 지정하여 ref를 생성합니다:
git remote set-head origin <default-branch>. 이는 로컬 추적 reforigin/<default-branch>가 있을 때 항상 동작합니다. 단일 브랜치 클론처럼 해당 ref가 없다면 먼저 브랜치를 가져옵니다.git remote set-branches --add origin <branch>를 실행한 다음git fetch origin을 실행하고, set-head 명령을 다시 실행합니다. 그런 다음/security-review를 다시 실행합니다. - 브랜치를 지정하지 않으려면
git fetch origin을 실행한 다음git remote set-head origin --auto를 실행합니다. 이 명령은 원격에 어떤 브랜치가 기본인지 묻습니다. 원격이 비어 있거나 HEAD가 아무도 푸시하지 않은 브랜치를 가리켜 기본 브랜치를 알리지 않으면error: Cannot determine remote HEAD로 실패하며, 이 경우 브랜치를 명시적으로 지정합니다. 클론이 해당 브랜치를 가져오지 않으면error: Not a valid ref로 실패하며, 이 경우 먼저 위와 같이 refspec을 넓힙니다. - 저장소에 원격이 없으면
git remote add origin <url>로 원격을 추가하고 ref를 생성하기 전에 fetch합니다. 원격이 비어 있으면 먼저git push -u origin HEAD로 브랜치를 푸시하고 set-head 명령에서 해당 브랜치를 지정합니다. 그러면origin/HEAD가 방금 푸시한 브랜치를 가리키므로, 브랜치가 이와 달라질 때까지/security-review는 빈 diff를 보게 됩니다.
스킬 또는 명령의 셸 명령이 실행되지 않음
No shell command in <name> was run은 해당 스킬 또는 명령 파일의 !`<command>` 동적 컨텍스트 명령에 Bash 또는 PowerShell 도구가 거부하는 문자가 포함되어 있다는 의미입니다:
- 두 도구 모두: 탭이나 줄바꿈 이외의 원시 제어 문자
- PowerShell 도구: 추가로 U+FEFF 또는 U+180E
�로 표시됩니다:
- 메시지 끝에 인용된 명령에서 각
�를 찾습니다. 해당 문자를 스킬 또는 명령 파일에서, 또는 파일에 대입되는 인수나 옵션에서 제거합니다.
4,000,000자 제한을 초과한 스킬, 명령 또는 훅
more than 4,000,000 characters가 포함된 메시지는 스킬, 명령, 또는 프롬프트 훅이나 에이전트 훅이 실행되지 않았다는 의미입니다. 긴 텍스트를 인수로 붙여 넣었다면 이를 파일로 저장하고, 텍스트가 대화에 남아 있으므로 /clear를 실행한 뒤 파일 경로를 전달합니다. Code Mode 밖에서는 제한을 초과한 PreToolUse 프롬프트 훅이나 에이전트 훅이 호출을 차단하지 않습니다. 이러한 제한이 없는 명령 훅을 사용하십시오.
Input must be provided when using --print
인수 없는 claude는 대화형 UI를 시작하기 위해 stdout이 터미널이어야 합니다. stdout이 리디렉션되거나, PowerShell ISE 및 일부 IDE 출력 창처럼 콘솔이 실제 터미널이 아니면 claude는 대신 비대화형으로 실행됩니다. 이는 프롬프트가 필요한 claude -p와 같은 모드이므로, 플래그를 전달하지 않았더라도 메시지에 --print가 표시됩니다. 프롬프트 없이, 그리고 stdin으로 아무것도 파이프하지 않은 채 -p/--print를 전달하면 어디에서나 같은 오류가 발생합니다.
- 대화형으로 사용하려면 실제 터미널에서
claude를 실행합니다. ISE 대신 Windows Terminal이나 PowerShell 콘솔을, 출력 창 대신 IDE의 통합 터미널을 사용합니다 - 일회성으로 사용하려면 프롬프트를 전달합니다:
claude -p "your question", 또는echo "your question" | claude -p로 파이프합니다
Claude Code can’t read the keyboard here
-p 없이 claude를 실행하여 대화형 세션이 시작되었지만, 표준 입력이 터미널이 아닙니다. 무언가가 입력을 파이프하거나 리디렉션했거나, claude를 실행한 프로그램이 자체 입력 스트림을 제공했습니다.
대화형 세션에는 키 입력을 읽어 올 터미널이 필요하며, 터미널이 없을 때 Claude Code의 동작은 플랫폼에 따라 다릅니다:
- Windows: Claude Code는 인터페이스를 시작하는 대신 메시지를 stderr에 출력하고 코드 1로 종료합니다
- macOS 및 Linux: Claude Code는
/dev/tty에서 키 입력을 읽어 세션을 시작하며, 파이프된 텍스트는 첫 번째 프롬프트가 됩니다. 이 메시지는/dev/tty를 열 수 없을 때 표시되며, 첫 줄에는 Windows 문구 대신/dev/tty가 언급됩니다.
- 대화형으로 작업하려면 입력을 파이프하거나 리디렉션하지 말고 터미널에서
claude를 직접 실행합니다 - 스크립트 등에서 대화형 인터페이스 없이 응답을 받으려면
-p를 추가하고claude -p "your question"또는echo "your question" | claude -p처럼 프롬프트를 인수로 전달하거나 stdin으로 전달합니다.--continue및--resume <session-id>에서도 동일하게 작동합니다.
Raw mode is not supported를 포함한 오류와 함께 실패했습니다.
대신 claude install 중에 Raw mode is not supported가 표시된다면 설치 중 Raw mode is not supported를 참조하세요.
Input contained only whitespace
비대화형 모드에서 Claude Code는 공백, 탭 또는 줄 바꿈으로만 이루어진 프롬프트를 전송하지 않고 거부합니다. API가 보이는 텍스트가 없는 메시지를 거부하기 때문입니다. 표시되는 메시지는 빈 프롬프트가 어디에서 왔는지에 따라 다릅니다:claude -p의 프롬프트 인수 또는 파이프된 stdin:claude가Error: Input contained only whitespace. Provide a prompt with text through stdin or as a prompt argument when using --print와 함께 종료됩니다- 실행 중인
--input-format stream-json또는 Agent SDK 세션에 제출된 메시지: Claude Code는 모델을 호출하지 않고 턴을 종료하며 세션은 계속 사용할 수 있습니다. 거부 내용은 정보 메시지와 턴의 결과 텍스트로 전달됩니다:Blank prompt — the message was only whitespace, so nothing was sent to the model.
- 프롬프트에 보이는 텍스트를 포함합니다. 스크립트가 변수나 파일에서 프롬프트를 구성한다면 Claude Code를 호출하기 전에 소스가 비어 있지 않은지 확인합니다.
stream-json input carried over 256M characters with no newline
프로그램이claude -p --input-format stream-json 실행에 줄 바꿈 없이 268,435,456자를 초과하는 데이터를 stdin으로 보냈기 때문에, Claude Code는 더 많은 입력을 버퍼링하는 대신 이 오류를 stderr에 출력하고 코드 1로 종료합니다. 메시지에서는 이 한도를 256M으로 표시합니다. v2.1.257 이전에는 Claude Code가 이러한 입력을 제한 없이 버퍼링하여 프로세스가 충돌하거나 강제 종료될 때까지 메모리 사용량이 증가했습니다.
- stdin으로 무엇이 파이프되는지 확인합니다.
--input-format stream-json을 사용할 때는 모든 메시지가 줄 바꿈으로 끝나는 하나의 JSON 줄이어야 합니다 - 대신 일반 텍스트를 보내려면
--input-format stream-json을 제거합니다.claude -p는 기본적으로 stdin에서 일반 텍스트 프롬프트를 읽습니다
Unknown command
대화형 터미널 세션에서 이 세션의 어떤 명령과도 일치하지 않는/ 이름을 제출했기 때문에, Claude Code는 아무것도 실행하지 않고 해당 이름을 알려 줍니다:
/help를/hepl로 입력한 것과 같은 오타. 명령 메뉴가 입력 내용과 일치시키는 방식에서 제출 전에 가까운 일치 항목을 선택하는 방법을 다룹니다- 존재하지만 플랫폼, 요금제 또는 인증 방법 같은 요구 사항이 충족되지 않아 이 세션에서 사용할 수 없는 명령.
/web-setup,/schedule또는/auto-mode-setup항목을 참조하세요. 일부 명령은 조직 정책으로 비활성화된 경우Cloud sessions are disabled by your organization's policy처럼 자체 메시지로 응답합니다 - 이 세션에 설치되지 않았거나 연결되지 않은 플러그인 또는 MCP 서버의 명령
/ 이름에 이런 방식으로 응답합니다. 그 밖의 모든 세션에서는 명령이 실행되지 않았다는 안내와 세션에서 Claude가 실행할 수 있는 명령 목록과 함께 프롬프트를 일반 메시지로 Claude에 보냅니다. 해당 세션은 다음과 같습니다:
-p실행- Agent SDK 애플리케이션
- Desktop 앱의 Code 탭
- VS Code 확장 프로그램의 채팅 패널
- 클라우드 세션 및 클라우드 예약 작업
Unknown command로 응답했습니다.
Claude Code는 /로 시작하는 모든 프롬프트를 명령으로 취급하지는 않습니다. / 뒤의 첫 단어가 Lean 문서 주석을 여는 /--처럼 문장 부호로 시작하거나 /var/log/syslog 같은 경로인 경우, 프롬프트를 일반 메시지로 Claude에 보냅니다.
v2.1.236 이전에는 명령 메뉴에 입력한 이름과 가까운 항목이 나열된 상태에서 Enter를 누르면 Claude Code가 해당 항목을 실행했기 때문에, /hepl 같은 오타는 이 메시지를 표시하는 대신 /help를 실행했습니다.
해결 방법:
- 제안된 이름을 실행하거나,
/다음에 이름의 일부를 입력하여 이 세션에서 사용할 수 있는 명령을 확인합니다 - Claude Code가 문서화된 명령을 알 수 없다고 보고하면 명령 레퍼런스에서 해당 행에 명시된 요구 사항을 확인합니다
Diff is too large for ultrareview
커밋되지 않은 변경 사항과 스테이징된 변경 사항을 포함하여 브랜치와 기본 브랜치 사이의 diff가 ultrareview의 크기 제한을 초과하므로,/code-review ultra와 claude ultrareview 하위 명령은 클라우드 세션이 시작되기 전에 리뷰를 거부합니다. 거부된 리뷰는 무료 실행 횟수를 사용하지 않으며 사용량 크레딧도 청구되지 않습니다. 메시지에는 적용 중인 제한, diff의 크기, 변경된 줄이 가장 많은 파일이 표시됩니다. v2.1.216 이전에는 메시지에 원시 diff 통계만 표시되었습니다.
PR #<N> is too large for ultrareview로 시작하며 PR의 파일 수와 줄 수를 표시합니다.
해결 방법:
/code-review ultra develop처럼 작업에 더 가까운 기본 브랜치를 전달하여 해당 브랜치와의 diff만 리뷰하도록 합니다- 변경 사항을 더 작은 브랜치로 나누고 각각 리뷰합니다. 메시지에 표시된 파일이 변경된 줄을 가장 많이 차지하므로, 먼저 해당 파일들을 별도의 브랜치로 옮깁니다.
Could not find merge-base with the base branch
/code-review ultra와 claude ultrareview 하위 명령은 브랜치와 기본 브랜치 사이의 diff를 리뷰하며, 이를 위해서는 두 브랜치가 공유하는 커밋이 필요합니다. git merge-base가 공유 커밋을 찾지 못하면 Claude Code는 클라우드 세션이 시작되기 전에 리뷰를 거부합니다. Claude Code가 완전함을 확인할 수 있고 브랜치가 하나 이상 있는 클론에서는 거부하는 대신 추적되는 모든 파일을 리뷰하는 방식으로 대체합니다. 이 거부는 기본 브랜치를 전혀 찾을 수 없는 경우, Claude Code가 클론이 완전한지 확인할 수 없는 경우, 또는 SHA-256 객체 형식처럼 전체 트리 diff가 불가능한 드문 저장소에서 표시됩니다.
- 기본 브랜치를 전달하지 않은 경우: Claude Code는 저장소의 기본 브랜치와 비교했으며, 위 예시처럼 기본 브랜치를 명시적으로 전달하도록 제안합니다
- 이미 클론에 있던 기본 브랜치를 전달한 경우: 힌트는
Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)입니다 - 클론에 없던 기본 브랜치를 전달한 경우: Claude Code는 비교 전에 origin에서 해당 브랜치를 가져왔습니다. 힌트는
<branch> was fetched from origin but shares no history with HEAD. If another branch is your real base, pass it explicitly (`/code-review ultra <branch>`)입니다. Claude Code가 클론이 shallow 클론인지 판단할 수 없는 경우에는 대신git fetch --unshallow origin을 제안합니다. v2.1.221 이전에는 가져온 모든 기본 브랜치에 대해 힌트가git fetch --unshallow origin을 제안했으며, 완전한 클론에서는 이 명령이fatal: --unshallow on a complete repository does not make sense와 함께 실패합니다.
- 다른 브랜치가 실제 기본 브랜치라면
/code-review ultra <branch>로 명시적으로 전달합니다 - 클론에 전체 기록이 없을 수 있다면
git fetch --unshallow origin을 실행하고 리뷰를 다시 실행합니다
Your checkout has no branches
체크아웃에는 커밋이 있지만 브랜치가 없을 수 있습니다.git init을 실행한 뒤 git fetch <url>과 git checkout FETCH_HEAD를 실행하면 ref가 없는 detached HEAD 상태가 됩니다. Claude Code는 ultrareview를 위해 저장소를 업로드할 때 git bundle로 패키징하는데, 브랜치나 다른 ref가 없는 저장소는 번들로 만들 수 없으므로 /code-review ultra와 claude ultrareview 하위 명령은 클라우드 세션이 시작되기 전에 리뷰를 거부합니다.
git checkout -b <name>으로 현재 커밋에 브랜치를 만든 다음 리뷰를 다시 실행합니다
No GitHub account is connected to your Claude account
/code-review ultra <PR#> 또는 claude ultrareview <PR#>를 실행하면 Claude Code는 클라우드 세션을 만들기 전에 Claude 계정에 연결된 GitHub 계정이 PR의 저장소에 접근할 수 있는지 서버에 확인합니다. 연결된 계정이 없거나 연결이 만료되어 클라우드 클론이 실패할 것이므로 Claude Code는 실행을 거부합니다. 거부된 실행에 대해 Claude Code는 무료 실행 횟수를 사용하거나 사용량 크레딧을 청구하지 않습니다.
/web-setup을 사용할 수 없는 경우 메시지에는 claude.ai 링크만 표시됩니다.
해결 방법:
/web-setup을 실행하여 GitHub CLI 로그인을 Claude 계정에 연결하거나, claude.ai/connect-github에서 계정을 연결합니다- 연결 후 1분 정도 지나서 리뷰를 다시 실행합니다
Your connected GitHub account can’t see the repository
/code-review ultra <PR#> 또는 claude ultrareview <PR#>를 실행했지만 Claude 계정에 연결된 GitHub 계정이 PR의 저장소를 읽을 수 없어 클라우드 클론이 실패할 것이므로 Claude Code는 실행을 거부합니다. 거부된 실행에 대해 Claude Code는 무료 실행 횟수를 사용하거나 사용량 크레딧을 청구하지 않습니다.
/web-setup을 사용할 수 없는 경우 메시지에는 앱 설치 안내만 표시됩니다.
해결 방법:
- 로컬
ghCLI가 저장소를 읽을 수 있다면/web-setup을 실행하여 해당 로그인을 Claude 계정에 연결합니다 - 변경 후 리뷰를 다시 실행합니다
The GitHub App preflight failed transiently
로컬 저장소에서 클라우드 세션을 시작했는데 두 단계가 함께 실패했습니다. Claude Code가 저장소의 번들을 빌드하거나 업로드하지 못했습니다. 업로드 전에 Claude Code는 클라우드 서비스가 GitHub에서 저장소를 클론할 수 있는지 확인했는데, 이 확인은 명확한 답 대신 네트워크 오류, 시간 초과 또는 일시적인 서버 오류처럼 재시도로 해결될 수 있는 오류로 끝났습니다. 전체 메시지는Could not upload repo bundle (<error>)처럼 번들을 중단시킨 원인으로 시작하고 사전 확인 문장으로 끝납니다:
- 잠시 후 명령을 다시 실행합니다. GitHub 확인이 통과하면 Claude Code는 GitHub 클론에서 세션을 시작할 수 있으므로, 실패한 업로드가 더 이상 실행을 막지 않습니다
- 재시도가 계속 실패하면 메시지 앞부분에 업로드를 중단시킨 원인이 표시됩니다. 그 원인이 직접 해결할 수 있는 것이라면 해결하여 세션이 로컬 저장소에서 시작될 수 있도록 합니다
Please set up GitHub on https://claude.ai/code로 끝냈으며, 설정 안내로는 일시적인 실패를 해결할 수 없습니다.
저장소 업로드가 git 설정을 따를 수 없는 경우
로컬 저장소를 업로드하는 클라우드 세션 또는 브랜치의 ultrareview를 시작했는데, 업로드가 파일에 적용되는 attribute 규칙을 결정하는 git 설정 중 하나를 따를 수 없습니다. 업로드가 그대로 진행되어 규칙을 놓치면, clean 필터가 암호화하는 파일처럼 git이 저장 전에 변환하는 파일이 디스크에 있는 그대로 클라우드에 전송될 수 있습니다. 따라서 Claude Code는 업로드를 거부하며 아무것도 업로드되지 않습니다:core.attributesFile과 attr.tree에 대해서도 각각의 해결 방법과 함께 동일한 거부가 표시됩니다.
메시지에는 git 구성이 include 또는 includeIf 지시문을 통해 불러오는 설정 파일이 표시될 수 있으며, 해당 지시문의 조건이 이 저장소에 적용되지 않는 경우에도 마찬가지입니다.
해결 방법:
- 메시지의 마지막 문장에 있는 해결 방법을 적용합니다
GitHub isn’t connected to your Claude account
/autofix-pr 등으로 로컬 저장소에서 클라우드 세션을 시작했습니다. Claude 계정에 연결된 GitHub 계정이 없거나 연결이 만료되어 Claude Code가 실행을 거부합니다:
/schedule로 클라우드 예약 작업을 만들 때는 동일한 메시지가 저장소 이름과 함께 설정 안내로 표시되며, 이 안내는 작업 생성을 막지 않습니다.
해결 방법:
/web-setup을 실행하여 GitHub CLI 로그인을 Claude 계정에 연결하거나, claude.ai/connect-github에서 계정을 연결합니다. 두 방법의 차이는 GitHub 인증 옵션을 참조하세요.- 연결 후 1분 정도 지나서 명령을 다시 실행합니다
GitHub 조직 정책이 Claude를 차단하는 경우
Claude Code 프롬프트에서/autofix-pr처럼 클라우드 세션을 시작하는 명령을 실행했습니다. Claude Code는 세션을 만들기 전에 GitHub에서 Claude의 저장소 접근 권한을 확인하는데, GitHub 조직에 Claude를 차단하는 정책이 있어 GitHub가 거부했습니다. Claude Code는 그 지점에서 중단하고 해당 정책을 명시한 메시지를 표시합니다.
IP 허용 목록이 접근을 차단하는 경우 메시지는 다음과 같습니다:
- IP 허용 목록: GitHub 조직 또는 엔터프라이즈의 소유자에게 Anthropic의 아웃바운드 IP 주소를 허용하도록 요청합니다. 주소와 변경할 GitHub 설정은 GitHub 허용 목록 및 방화벽을 참조하세요.
- 싱글 사인온: claude.ai/customize/connectors에서 GitHub 연결을 해제한 다음 다시 연결합니다. GitHub가 요청하면 조직 옆의 Authorize를 클릭하여 새 연결이 해당 조직의 싱글 사인온에 대해 인가되도록 합니다.
- 조건부 액세스 정책: GitHub Enterprise 또는 Microsoft Entra ID 관리자에게 해당 정책에서 Claude를 허용하도록 요청합니다
- 변경 후 명령을 다시 실행합니다
Single sign-on authorization needed
/install-github-app을 실행하고 SAML 싱글 사인온을 적용하는 조직의 저장소를 선택했습니다. 설정 전에 Claude Code는 GitHub CLI로 저장소 접근 권한을 확인하는데, gh 토큰이 아직 해당 조직에 대해 인가되지 않았기 때문에 GitHub가 확인을 거부했습니다. 마법사는 인가 단계와 함께 경고를 표시합니다:
gh auth refresh -h github.com -s repo,workflow를 실행하여repo및workflow범위로 GitHub CLI 로그인을 다시 인가하고, GitHub가 싱글 사인온을 요청하면 조직을 인가합니다GH_TOKEN에 개인 액세스 토큰을 사용하여 인증하는 경우 github.com/settings/tokens를 열고 토큰에서 Configure SSO를 선택한 다음 조직을 인가합니다/install-github-app을 다시 실행합니다
Admin permissions required 경고를 표시했습니다.
Failed to resume the conversation
Claude Code가claude --resume 선택기에서 선택한 세션의 저장된 트랜스크립트를 읽거나 처리할 수 없어, 부분적으로 로드된 상태로 계속하지 않고 프로세스를 종료합니다. 메시지에는 재시도할 명령이 포함됩니다:
/resume 선택기는 대신 대화에 Failed to resume conversation을 표시하며, 현재 세션은 계속 실행됩니다. v2.1.216 이전에는 claude --resume 선택기에서 재개에 실패하면 이 메시지를 표시하는 대신 Resuming conversation… 스피너에 무기한 머물렀습니다.
해결 방법:
- 메시지에 있는 세션 ID로
claude --resume <session-id>를 실행하여 재시도합니다 - v2.1.285 이전 버전에서 재시도가 같은 방식으로 실패하면
claude update를 실행하고 다시 재개합니다. 해당 버전들은 저장된 트랜스크립트에 읽을 수 없는 항목이 있으면 재개에 실패합니다. - 재시도가 다시 실패하면
claude를 실행하여 새 세션을 시작합니다
No conversation found with the session ID
claude --resume <session-id>에 세션 ID를 전달했지만 일치하는 저장된 트랜스크립트가 없습니다:
- 잘못 입력한 ID: 비대화형 실행의 경우 ID는
--output-format json출력의session_id필드입니다 - 삭제된 트랜스크립트: Claude Code는 보존 정리 규칙에 따라 보존 기간(기본값 30일)이 지나면 트랜스크립트를 삭제합니다
- 다른 머신: Claude Code는 트랜스크립트를 로컬에 저장하므로, 세션이 실행된 머신에서 재개해야 합니다
- 중복 복사본:
~/.claude/projects아래의 프로젝트 디렉터리를 복사하여 두 트랜스크립트가 같은 ID를 갖게 되면, Claude Code는 임의로 한 복사본을 재개하지 않고 이 메시지를 표시합니다
- 대화형 세션의 경우
claude --resume으로 세션 선택기를 열고Ctrl+A를 눌러 이 머신의 모든 프로젝트로 범위를 넓힌 다음 세션을 선택합니다 claude -p또는 Agent SDK로 만든 세션은 선택기에 표시되지 않으므로, 원래 실행에서 출력된session_id와 ID를 다시 대조합니다
Windows reported an error (EBADF) when Claude Code read this session’s transcript file
Windows에서 세션을 재개했는데, 저장된 트랜스크립트 파일이 정상적으로 열린 후 읽기가 시스템 오류 EBADF로 실패했습니다. 시스템 오류는 읽기가 실패한 이유를 알려 주지 않으므로, 메시지에서 가능한 원인과 시도할 방법을 제안합니다:Failed to resume session <session-id>처럼 명령 자체의 실패 줄 뒤에 표시됩니다. claude --resume 또는 claude -p 명령은 메시지를 표시한 후 코드 1로 종료합니다. 세션 내에서 /resume을 실행한 경우에는 현재 세션이 계속 실행됩니다.
해결 방법:
- 보안, 암호화 또는 엔드포인트 관리 도구처럼 파일 읽기를 검사하거나 가로채는 소프트웨어에서 세션 트랜스크립트가 있는 폴더를 제외합니다. 트랜스크립트는 기본적으로
%USERPROFILE%\.claude\projects아래에 있으며,CLAUDE_CONFIG_DIR이 지정한 경우 해당 디렉터리 아래에 있습니다 - 제외 항목을 추가할 수 없다면 대신 해당 소프트웨어의 허용된 애플리케이션에 Claude Code를 추가합니다
- 세션을 다시 재개합니다
claude --resume <session-id>는 Failed to resume session <session-id>에서 끝났고, -p 실행은 Failed to resume session: EBADF: bad file descriptor, read처럼 시스템 오류 텍스트만 출력했습니다.
Cannot switch renderers in this session
렌더러를 전환하면 Claude Code가 프로세스를 재시작합니다. Claude Code가 재시작을 거부하는 세션에서/tui를 실행했으므로, 전환하지 않고 아무것도 저장하지 않습니다. 표시되는 메시지로 원인을 알 수 있습니다:
Cannot switch renderers while work is running in the background: 백그라운드 셸이나 서브에이전트처럼 재시작 시 중단될 백그라운드 작업이 실행 중입니다. 작업이 끝날 때까지 기다리거나/tasks로 중지한 다음/tui fullscreen또는/tui default를 다시 실행합니다Cannot switch renderers in this session: 세션에 Claude Code가 재시작된 프로세스로 전달할 수 없는 제한이 있습니다. v2.1.234 이전에는 Claude Code가 그래도 재시작했고, 다시 시작된 세션은 해당 제한 없이 실행되었습니다
launch flags: a custom system prompt, a tool allowlist, or restricted settings: Claude Code가 재시작된 프로세스로 다시 전달하지 않는 플래그로 세션을 시작했습니다. 이러한 플래그에는--system-prompt,--system-prompt-file,--append-system-prompt-file,--tools허용 목록,--setting-sources,--permission-prompt-tool이 포함됩니다permission rules set for this session only: 훅 또는 SDK 호출자의 권한 업데이트가session대상으로 거부 또는 확인 규칙을 추가했습니다. 세션 범위의 허용 규칙은 거부를 유발하지 않습니다. 재시작하면 해당 규칙이 삭제되며, Claude Code가 대신 다시 확인을 요청합니다ask-before-running rules with no command-line form: 훅 또는 SDK 호출자의 권한 업데이트가 Claude Code가--allowed-tools및--disallowed-tools로 다시 전달하는 규칙과 함께 확인 규칙을 추가했습니다. 확인 규칙에 해당하는 플래그는 없습니다permission rules a command line cannot carry intact및added directories a command line cannot carry intact: 권한 업데이트가 세션 도중에 규칙이나 디렉터리 경로를 추가했습니다. 재시작된 프로세스의 명령줄은 해당 텍스트를 같은 값으로 전달할 수 없습니다
- 해당 제한 없이 시작한 세션에서
/tui fullscreen을 실행하거나, 되돌리려면/tui default를 실행합니다. Claude Code는 그 세션에서tui설정을 저장합니다
Can’t restart while work is running or Remote Control is connected
Claude Code가 재시작하지 않았으며, 세션은 그대로 계속 실행됩니다. 메시지에 있는 해결 방법을 따르세요.Claude Code couldn’t restart
이 메시지에 대화가 저장되었다고 표시되면, 대화는 디스크에 있으며 중단된 지점부터 이어서 진행할 수 있습니다. Claude Code가 자체적으로 재시작하던 중, 예를 들어/tui를 실행한 후 전체 화면 렌더링으로 전환하거나 전체 화면 렌더링에서 전환하던 중 새 프로세스를 시작할 수 없어 상태 1로 종료했습니다:
/tui가 새 세션의 첫 입력이었던 경우처럼 재시작 시 다시 열 대화가 없었다면 메시지는 Claude Code couldn't restart. Start Claude Code again.입니다.
해결 방법:
- 셸에서
claude를 다시 실행합니다. 메시지에 대화가 저장되었다고 표시되었다면 새 세션에서/resume을 실행하고 대화를 선택합니다. 목록에 없다면 세션 선택기의 범위를 넓힙니다 - 재시작이 계속 실패하면 셸에서
claude --debug-file claude-debug.log로 Claude Code를 시작합니다. 해당 세션에서 재시작이 실패하면, 시작한 디렉터리의claude-debug.log에 운영 체제의 오류와 함께Failed to relaunch:줄이 기록됩니다. 문제를 보고할 때 해당 줄을 포함합니다
Couldn’t open Claude Desktop
세션에서/desktop 또는 그 별칭인 /app을 실행했거나 셸에서 claude --desktop을 실행했는데, Claude Code가 Claude Desktop을 열기 위해 사용하는 시스템 명령이 실패했습니다. /desktop 이후에는 세션이 터미널에 그대로 남아 있으며, claude --desktop은 Error: 접두사 없이 메시지를 출력하고 상태 1로 종료합니다.
괄호 안의 텍스트는 실패한 명령을 나타내며, 종료 상태와 오류 출력의 첫 줄이 있는 경우 함께 표시됩니다. macOS에서는 이 예시처럼 open 명령이며, Windows에서는 rundll32입니다:
- Claude Desktop을 직접 연 다음
/desktop또는claude --desktop을 다시 실행합니다 - 실패한 명령의 전체 오류 출력을 확인하려면
/debug로 디버그 로깅을 켜고/desktop을 다시 실행하거나,claude --desktop --debug-file <path>를 실행한 다음 디버그 로그를 확인합니다
Open Claude Desktop and run /desktop again.으로 끝났습니다. v2.1.275 이전에는 메시지가 Failed to open Claude Desktop. Please try opening it manually.였으며 무엇이 실패했는지 알려 주지 않았습니다.
/terminal-setup이 Zed 키맵을 변경하지 않은 경우
Zed에서/terminal-setup을 실행했지만 Claude Code가 Zed keymap.json 업데이트를 완료할 수 없어 파일을 그대로 두었습니다.
각 메시지는 키맵 경로를 표시하고, 직접 추가할 키보드 단축키 블록으로 끝납니다:
Couldn't read your Zed keymap, so it was left unchanged.: 파일 권한 등의 이유로 Claude Code가 파일을 읽을 수 없었습니다Your Zed keymap isn't a readable list of keybindings, so it was left unchanged.: 파일은 정상적으로 읽었지만,//주석과 후행 쉼표를 허용하더라도 키보드 단축키 블록의 배열로 파싱되지 않습니다Couldn't back up your Zed keymap; not modifying it.: Claude Code가 파일을 옆에 있는.bak백업으로 복사할 수 없어 아무것도 변경하지 않았습니다Couldn't update your Zed keymap, so it was left unchanged.: 병합된 결과가 해당 단축키를 포함하는 유효한 키맵으로 검증되지 않아, Claude Code가 파일에 쓰지 않고 결과를 폐기했습니다. 키가 중복된 키보드 단축키 블록이 원인일 수 있습니다
- 메시지의 블록을 메시지에 표시된 경로에 있는
keymap.json의 최상위 배열에 복사합니다 isn't a readable list of keybindings의 경우 구문 오류를 수정하거나 파일의 최상위 값을 배열로 만든 다음/terminal-setup을 다시 실행합니다
/terminal-setup이 // 주석이나 후행 쉼표를 사용하는 Zed 키맵을 파싱할 수 없었으며, 파일 전체를 자체 단축키만으로 교체하면서 단축키가 설치되었다고 보고했습니다. 이전 버전이 교체한 키맵을 복원하려면 여러 줄 프롬프트 입력에 설명된 .bak 백업 파일을 사용하세요.
Skill usage reports are not available on this connection
휴대폰이나 브라우저에서 Remote Control을 통해/skill-doctor를 실행했습니다. Claude Code는 Remote Control을 통해 스킬 사용 보고서를 보내지 않으며, 대신 이 메시지로 응답합니다:
- 세션이 실행 중인 머신의 터미널에서
/skill-doctor를 실행하거나, 그곳에서claude -p "/skill-doctor"를 실행합니다
Custom output styles can’t be selected over Remote Control
Remote Control을 통해 모바일 앱이나 웹에서/output-style을 실행했거나, 세션으로 중계된 메시지에 명령이 포함되어 전달되었습니다. 이러한 턴은 계정 소유자가 보낸 것이 아닐 수 있으므로, Claude Code는 해당 턴에서 기본 제공 스타일만 나열하고 선택하며, 명령이 스타일을 나열하거나 입력한 이름을 인식하지 못할 때마다 이 안내를 추가합니다. 사용자 지정 스타일 이름은 존재하지 않는 이름과 동일한 응답을 받습니다:
/output-style concise처럼 기본 제공 스타일을 선택합니다- 사용자 지정 스타일을 사용하려면 프로젝트의
.claude/settings.local.json에서outputStyle을 설정하거나, 세션 자체의 터미널이 있다면 그곳에서/output-style <style>을 실행합니다
Output styles are saved to local settings which this session doesn’t load
설정 소스에서local을 제외한 세션에서 /output-style <style> 또는 /config outputStyle=<style>로 출력 스타일을 전환하려고 했습니다. 예를 들어 settingSources에서 "local"을 제외한 Agent SDK 세션이나, local을 제외한 --setting-sources 값으로 시작한 CLI 세션이 있습니다. 두 명령 모두 스타일을 .claude/settings.local.json에 저장하는데, 이러한 세션은 이 파일을 다시 읽지 않으므로 Claude Code는 효과가 없을 설정을 쓰는 대신 거부합니다:
- 세션의 설정 소스에
local을 추가하고 다시 전환합니다 - 프로젝트의
.claude/settings.json이나~/.claude/settings.json처럼 세션이 로드하는 설정 파일에서outputStyle키를 설정합니다. TypeScript SDK에서는 대신 인라인settings객체 안에서outputStyle을 설정합니다. 출력 스타일 활성화를 참조하세요
/recap only runs when you ask for it yourself
/recap 요청이 사용자 본인의 입력에서 온 것이 아닙니다. Slack, Teams 또는 프로젝트 스레드에서 세션으로 중계된 메시지에 포함되어 있었거나, 클라우드 예약 작업이나 다른 프로그램이 보낸 프롬프트에 포함되어 있었습니다.
중계된 메시지는 사용자 본인이 작성했더라도 이 안내를 받습니다. Claude Code는 중계되거나 자동화된 메시지가 세션을 실행하는 계정의 소유자에게서 온 것인지 구분할 수 없으므로, 요약 대신 이 안내로 응답합니다:
claude -p에 전달하는 /recap이나, 사용자 본인의 Agent SDK 애플리케이션이 자신이 시작한 세션에 보내는 /recap은 본인의 입력으로 간주됩니다.
해결 방법:
- 세션을 직접 열고 그곳에서
/recap을 실행합니다. 세션의 터미널, Desktop 앱 또는 모바일 앱, claude.ai/code, 또는 Remote Control을 통해 실행할 수 있습니다 - 클라우드 예약 작업이나 다른 프로그램이 보낸 경우 해당 프롬프트에서
/recap을 제거합니다
/feedback is disabled by your organization’s policy
이 메시지는 제품 피드백이 꺼져 있어 입력한 명령이 피드백 대화 상자를 열지 않는다는 의미입니다. 조직의 정책과 이전 거부 모두 이 메시지를 표시합니다:- 조직 정책: 조직의 정책이 Claude Code에서의 제품 피드백을 허용하지 않습니다.
/feedback,/bug,/share모두 이 메시지로 응답합니다. - 이전 거부: 피드백 서비스가 보낸 보고서를 거부했습니다. 예를 들어
Couldn't send feedback: Feedback has not been enabled for your organization.와 같은 경우입니다. 그러면/feedback과/bug가 이 메시지로 응답할 수 있습니다. 이 상태는 이 머신에서 해당 거부 시점부터 7일 동안 유지됩니다. Pro 및 Max를 포함한 모든 요금제에 적용됩니다.
- 버그를 보고하려면 github.com/anthropics/claude-code/issues에서 이슈를 엽니다. 그곳의 이슈는 누구나 읽을 수 있으므로 코드, 트랜스크립트 및 기타 기밀 정보는 제외합니다.
- 이전 거부 후에는 7일이 지날 때까지 기다린 다음, 서비스가 여전히 거부하는지 확인하기 위해 보고서를 다시 보냅니다
/feedback is disabled by your organization's policy. Contact your organization admin to enable it.였습니다.
플러그인 오류
이러한 오류는 플러그인 및 마켓플레이스 구성에서 발생합니다. 이 페이지의 메시지 중 하나를 생성하지 않는 플러그인 문제(예: 로드되지 않는 마켓플레이스 URL 또는 설치되지만 나타나지 않는 플러그인)의 경우 플러그인 문제 해결을 참조하십시오.plugin eval is currently in early access
claude plugin eval 또는 claude plugin eval init을 실행했으며 아무것도 수행하기 전에 다음 메시지 중 하나와 함께 종료 코드 1로 종료되었습니다:
claude --version을 실행한 다음claude update를 실행하고 새 세션에서 명령을 다시 실행하십시오. 플러그인 평가 요구 사항을 참조하십시오.- 현재 빌드에서 두 번째 메시지가 표시되면 다른
claude update후 나중에 다시 시도하십시오.
Marketplace is registered from an untrusted source
마켓플레이스가 공식 Anthropic 마켓플레이스용으로 예약된 이름으로 등록되어 있지만 등록된 소스가anthropics GitHub 저장소가 아닙니다. Claude Code는 마켓플레이스를 로드하거나 새로 고칠 때마다 예약된 이름을 다시 확인하므로 마켓플레이스와 여기서 설치된 플러그인이 로드되지 않습니다. v2.1.205 이전에는 이름이 예약되기 전에 등록된 항목이 계속 로드되었습니다.
can only be used with GitHub sources from the 'anthropics' organization 대신 읽습니다. claude plugin marketplace add는 동일한 확인을 실행하며 예약된 이름을 Failed to add marketplace: 다음에 동일한 예약된 이름 문장으로 거부합니다.
수행할 작업:
- 마켓플레이스가 이미 등록된 경우
claude plugin marketplace remove <name>을 실행한 다음 공식github.com/anthropics저장소에서 다시 추가하십시오. - 이름이 예약되기 전에 이름을 사용한 타사 마켓플레이스를 게시하는 경우 이름을 바꾸고 사용자에게 소스에서 다시 추가하도록 요청하십시오.
- 마켓플레이스 스키마에서 예약된 이름 목록을 참조하십시오.
Marketplace name is another spelling of a reserved name
마켓플레이스의 이름 자체는 예약된 이름이 아니지만 Claude Code는 이를 예약된 이름의 다른 철자로 취급합니다. 예약된 이름은 어떤 철자가 예약된 이름으로 간주되는지 나열합니다. Claude Code는 마켓플레이스를 추가할 때 이러한 이름을 거부합니다:/plugin, claude plugin install 및 claude plugin update는 경고합니다:
This marketplace's name is another spelling of "<reserved>", a reserved marketplace name. It is not exactly the reserved name it appears to be.로 읽습니다.
수행할 작업:
- 마켓플레이스의 이름을 예약된 이름의 철자를 지정하지 않는 이름으로 바꾸고 다시 추가하십시오.
- 무시된 항목 경고의 경우 제공하는
claude plugin marketplace remove명령을 실행하거나~/.claude/plugins/known_marketplaces.json에서 항목을 제거하십시오.
Claude Code refuses the marketplace name
등록된 마켓플레이스의 이름이 공식 Anthropic 마켓플레이스를 사칭합니다. 해당 섹션에 나열된 규칙에 따릅니다. 마켓플레이스가 확인이 이를 차단하기 전에 이러한 이름으로 등록된 경우 마켓플레이스와 여기서 설치된 플러그인이 로드되지 않습니다. Claude Code는 마켓플레이스의 카탈로그를 읽을 때마다 이름을 확인하기 때문입니다. 이름이 공식 이름을 모방할 때claude plugin list 및 /plugin Errors 탭은 다음과 같이 시작하는 메시지와 함께 영향을 받는 각 플러그인을 보고합니다:
Claude Code refuses this marketplace's name: it looks like one of Anthropic's own 대신 읽습니다. claude plugin marketplace add는 모든 사칭 이름을 Marketplace name impersonates an official Anthropic/Claude marketplace로 거부합니다.
v2.1.282 이전에는 claude plugin list 및 /plugin이 모방하는 이름의 플러그인을 마켓플레이스의 이름을 원인으로 명명하지 않고 로드 실패로 보고했습니다.
수행할 작업:
- 설정 파일이
"source": "settings"로 인라인 선언한 마켓플레이스를 유지하려면 이전 이름을 제거하기 전에 이름을 바꾸십시오. 마켓플레이스를 제거하면 설정 파일에서도 해당 항목이 삭제되기 때문입니다. Claude Code v2.1.292 이상에서는 메시지에 다음 단계가 나열됩니다:extraKnownMarketplaces아래에 마켓플레이스를 나열하는 각 설정 파일에서 항목의 키와 해당source.name에 공식 이름처럼 보이지 않는 새로운 일반 ASCII 이름 하나를 지정하십시오. 관리자가 조직의 관리형 설정을 통해 마켓플레이스를 추가하는 경우 이 단계는 관리자가 수행합니다.claude plugin marketplace remove <old-name>을 실행하거나/plugin의 Marketplaces 탭에서 이전 이름을 제거하십시오. 이렇게 하면 해당 플러그인도 제거되고 그 데이터, 옵션 및 비밀이 삭제됩니다.- Claude Code를 다시 시작하십시오. 파일이 프로젝트의 설정 파일인 경우 해당 프로젝트 폴더에서 시작하십시오. 그런 다음 이름이 바뀐 마켓플레이스에서 플러그인을 설치하십시오.
- 다른 마켓플레이스를 유지하려면 유지 관리자가 이름을 바꿀 때까지 기다린 다음
claude plugin marketplace update <name>을 실행하십시오. - 마켓플레이스를 제거하려면
claude plugin marketplace remove <name>을 실행하십시오. 이렇게 하면 마켓플레이스에서 설치된 플러그인도 제거되고 그 데이터, 옵션 및 비밀이 삭제됩니다. - 마켓플레이스를 게시하는 경우
marketplace.json에서 이름을 바꾸십시오. 사용자는 제거하는 대신 마켓플레이스를 업데이트합니다.
Marketplace is already added from a different source
세션 또는 셸에서 설치 명령의--marketplace <source>로 새 마켓플레이스 소스를 지정했습니다. Claude Code가 해당 소스에서 가져온 카탈로그의 이름이 이미 다른 소스에서 추가한 마켓플레이스의 이름과 같습니다. Claude Code는 기존 마켓플레이스를 대체하지 않고 유지하며, 플러그인은 설치되지 않습니다.
- 이미 추가한 마켓플레이스가 원하는 마켓플레이스인 경우 이름으로 설치하십시오:
/plugin install <plugin>@<name> - 새 소스로 전환하려면
/plugin marketplace remove <name>을 실행한 다음 설치를 다시 시도하십시오.
Plugin command references user_config in a shell command
플러그인 훅, 모니터 또는 MCPheadersHelper 명령이 ${user_config.KEY} 플러그인 옵션을 참조하며 대체된 문자열이 셸에 전달됩니다. 구성된 값에 $(...), 백틱 또는 ;이 포함되면 여기서 코드로 실행되므로 Claude Code는 값을 대체하는 대신 구성 요소를 시작하기를 거부합니다. 확인은 명령 템플릿에서 실행되므로 아직 값이 구성되지 않았을 때도 오류가 나타납니다. v2.1.207 이전에는 값이 셸 명령으로 대체되었습니다.
표현은 어느 사용 환경이 옵션을 참조했는지에 따라 다릅니다. 셸 형식 훅은 다음을 보고합니다:
headersHelper는 다음을 보고합니다:
- 훅의 경우
args배열을 추가하여 exec 형식에서 실행되도록 하십시오. 여기서 각${user_config.KEY}는 그 사이에 셸이 없는 하나의 인수가 됩니다. 또는 참조를 제거하고 스크립트 내에서$CLAUDE_PLUGIN_OPTION_<KEY>환경 변수를 읽으십시오. - 모니터의 경우 참조를 제거하고 모니터 스크립트가 구성 파일에서 값을 읽도록 하십시오.
headersHelper의 경우${user_config.KEY}를 셸 구문 분석되지 않는 서버의headers필드로 이동하거나 헬퍼 스크립트 내에서 값을 읽으십시오.
Plugin archive integrity check failed
플러그인의 마켓플레이스 항목이sha256 핀이 있는 archive 소스를 사용하며 다운로드된 파일의 다이제스트가 핀과 일치하지 않습니다. Claude Code는 설치를 거부하므로 플러그인 캐시에서 아무것도 변경되지 않습니다. 불일치에는 세 가지 가능한 원인이 있습니다:
- 작성자가 핀을 계산한 후 URL의 파일이 변경됨
- 작성자가 마켓플레이스 항목에 잘못된 다이제스트를 입력함
- URL이 작성자가 핀한 파일과 다른 파일을 제공함
- 플러그인을 게시하는 경우 URL이 제공하는 정확한 파일의 다이제스트를 다시 계산하십시오. 예를 들어
shasum -a 256 my-plugin.zip또는 PowerShell에서Get-FileHash -Algorithm SHA256 my-plugin.zip을 사용하고 마켓플레이스 항목의sha256을 업데이트하십시오. - 플러그인을 설치하는 경우
/plugin marketplace update <name>을 실행하여 항목이 수정된 경우 카탈로그를 새로 고친 다음 설치를 다시 시도하십시오. - 새로 고침 후에도 다이제스트가 계속 불일치하면 설치하기 전에 마켓플레이스 소유자에게 어떤 파일을 핀했는지 물어보십시오.
Path escapes plugin directory
플러그인의 구성 요소 경로 중 하나가 플러그인 디렉터리 외부로 이어지거나 플러그인 내부에 있는지 확인할 수 없으므로 Claude Code는 해당 경로를 삭제하고 플러그인의 나머지 부분을 로드합니다. 플러그인이plugin.json 또는 마켓플레이스 항목에서 선언한 경로의 경우 메시지의 구성 요소 이름(예: commands 또는 hooks)은 경로를 선언한 필드의 이름을 지정합니다.
claude plugin 명령 출력에서 동일한 오류는 Path escapes plugin directory: ./../shared.md (commands)로 읽습니다.
Claude Code는 ../shared-utils와 같이 플러그인 외부를 가리키는 경로와 마켓플레이스 심볼릭 링크 규칙이 허용하지 않는 플러그인 외부로 이어지는 심볼릭 링크를 모두 거부합니다. 심볼릭 링크의 경우 메시지는 경로가 확인되는 위치도 표시합니다:
hooks/hooks.json)의 전체 경로를 표시하는 메시지는 Claude Code가 해당 파일을 건너뛰었음을 의미합니다. Claude Code는 파일이 플러그인 내부에 있는지, 또는 로컬 마켓플레이스의 플러그인인 경우 해당 마켓플레이스 내부에 있는지 확인할 수 없으면 그 파일을 건너뜁니다. 메시지는 이러한 파일을 다음과 같이 표시된 컴포넌트 이름 아래에 보고합니다:
hooks/hooks.json:hooksmonitors/monitors.json:monitors- 플러그인 루트의
SKILL.md:skills
hooks/hooks.json에 대한 것입니다:
commands 경로를 플러그인 디렉터리 외부를 가리킬 때도 로드했습니다.
v2.1.257 이전에는 플러그인이 선언한 경로에 대한 확인이 경로의 철자만 보았으며 심볼릭 링크가 이어지는 위치는 보지 않았습니다.
수행할 작업:
- 플러그인을 설치했지만 유지 관리하지 않는 경우 메시지를 작성자에게 보고하십시오.
- 플러그인이 선언한 경로의 경우 참조된 파일을 플러그인 디렉터리 내부로 이동하고
./상대 경로로 경로를 가리키십시오. - 경로 또는 플러그인 내부에서 그 위에 있는 폴더가 플러그인 외부로 이어지는 심볼릭 링크인 경우 심볼릭 링크를 그것이 가리키는 대상의 복사본으로 바꾸십시오.
- 메시지가 플러그인이 선언한 경로에 백슬래시가 포함되어 있다고 말하면 경로를 정방향 슬래시로 작성하십시오. 예를 들어
./commands/deploy.md - 메시지가
EACCES로 끝나면 경로가 지정하는 파일 또는 폴더로 이어지는 모든 디렉터리에 대한 실행 권한을 복원하십시오. 경로 위의 디렉터리를 확인한 다음 도달하는 각 심볼릭 링크를 따라가 그것이 가리키는 위치로 이어지는 디렉터리를 확인하십시오. 다른 오류 코드의 경우 확인할 수 없는 경로의 원인 및 단계에서 찾아보십시오. - 동일한 마켓플레이스의 다른 플러그인과 파일을 공유하려면 플러그인 디렉터리 내의 심볼릭 링크로 연결하고 심볼릭 링크 규칙을 따르십시오.
Server file path not read
path not read 메시지는 Claude Code가 플러그인이 지정한 MCP 또는 LSP 서버 파일을 해당 파일의 경로 때문에 읽지 않았음을 의미합니다. 플러그인의 나머지 부분은 해당 파일이 정의하는 서버 없이 로드됩니다.
다음 예와 같이 경로가 플러그인 내부에 머물러 있더라도 .. 부분이 있으면 거부 대상이 됩니다:
- 플러그인을 설치했지만 유지 관리하지 않는 경우 메시지를 작성자에게 보고하십시오.
- 플러그인을 유지 관리하는 경우 서버 파일을 플러그인 디렉터리 내부에 두십시오. 매니페스트 또는 마켓플레이스 항목에서
./로 시작하고..가 없는 경로로 지정하십시오. 예:./servers/x.json - 동일한 마켓플레이스의 플러그인 간에 하나의 서버 파일을 공유하려면 심볼릭 링크 규칙에 따라 심볼릭 링크로 각 플러그인에 파일을 연결하십시오.
Plugin not loaded: its manifest was not read
Claude Code는.claude-plugin/plugin.json에 있는 마켓플레이스 플러그인의 매니페스트가 플러그인 내부에 있는지 확인할 수 없었으므로 해당 플러그인에서 아무것도 로드하지 않습니다. 로컬 마켓플레이스의 플러그인의 경우 Claude Code는 매니페스트가 해당 마켓플레이스 내부에 있는지도 확인할 수 없었습니다. 메시지는 /plugin Errors 탭에 나타나며, 끝부분의 이유는 Claude Code가 발견한 내용을 알려 줍니다.
예를 들어 이 메시지는 .claude-plugin 폴더가 마켓플레이스 외부로 이어지는 심볼릭 링크인 로컬 마켓플레이스의 플러그인에 대한 것입니다:
- 이유가
EACCES로 끝나면 매니페스트로 이어지는 모든 디렉터리에 대한 실행 권한을 복원하십시오. 매니페스트 위의 디렉터리를 확인한 다음 도달하는 각 심볼릭 링크를 따라가 그것이 가리키는 위치로 이어지는 디렉터리를 확인하십시오. 다른 오류 코드의 경우 확인할 수 없는 경로의 원인 및 단계에서 찾아보십시오. - 플러그인을 유지 관리하고 있으며 이유에 매니페스트가 확인되는 위치가 표시되어 있다면
.claude-plugin폴더 또는plugin.json자체가 그 위치로 이어지는 심볼릭 링크입니다. 해당 링크를 그것이 가리키는 대상의 복사본으로 바꾸십시오. - 플러그인을 설치했지만 유지 관리하지 않는 경우 메시지를 작성자에게 보고하십시오.
Path could not be checked
Claude Code는 플러그인 경로가 존재하는지 운영 체제에 물었고 “찾을 수 없음” 이외의 오류를 받았으므로 경로가 이름을 지정하는 것을 로드하지 않습니다. 플러그인의 얼마나 많은 부분이 로드되는지는 어느 경로가 실패했는지에 따라 다릅니다:- 플러그인의 기본 구성 요소 위치 중 하나(예:
skills/폴더,monitors/monitors.json파일 또는 플러그인 루트의SKILL.md): 플러그인의 다른 구성 요소는 여전히 로드됨 - 플러그인의 자체 디렉터리: 해당 플러그인에서 아무것도 로드되지 않음
/plugin에서 오류는 플러그인 아래에 나타나고 경로와 운영 체제가 반환한 코드의 이름을 지정합니다:
claude plugin list에서 동일한 오류는 Path not found: /home/user/my-plugin/skills (skills, ELOOP)로 읽습니다.
이 오류를 생성하는 원인은 다음을 포함합니다:
ELOOP: 경로의 심볼릭 링크가 자신을 가리키거나 루프를 형성함EIO또는ESTALE: 경로가 끊어지거나 오래된 네트워크 마운트에 있음EACCES: 경로 위의 디렉터리 중 하나가 이를 통과할 권한을 거부함
- 자신을 가리키는 심볼릭 링크를 실제 폴더로 바꾸거나 삭제하십시오.
- 경로가 네트워크 마운트에 있으면 공유를 다시 마운트하십시오.
- 코드가
EACCES이면 경로 위의 디렉터리에 대한 실행 권한을 복원하십시오. - 경로를 수정한 후
/reload-plugins을 실행하거나 Claude Code를 다시 시작하여 플러그인 또는 구성 요소를 로드하십시오.
Marketplace entry path does not stay inside the marketplace directory
플러그인의 마켓플레이스 항목이 Claude Code가 마켓플레이스의 자체 디렉터리 내부의 위치로 확인할 수 없는 소스 경로를 선언하므로 플러그인이 설치되거나 로드되지 않습니다. 거부는 다음을 포함합니다:- 절대 경로,
..로 마켓플레이스를 벗어나거나 네트워크 경로처럼 철자된 항목 경로 - macOS 및 Linux에서 선행
./이후 어디든지 백슬래시를 포함하는 항목 경로 - git 또는 URL과 같은 원격 소스에서 가져온 마켓플레이스의 항목이 마켓플레이스 디렉터리 외부로 확인되는 심볼릭 링크를 통해 대상에 도달함
- 마켓플레이스의
marketplace.json에 대한 직접 URL에서 추가된 마켓플레이스의 상대 항목: Claude Code는 해당 파일만 다운로드하므로 경로가 이름을 지정할 로컬 플러그인 파일이 없습니다. URL 기반 마켓플레이스에서 상대 경로가 있는 플러그인 실패를 참조하십시오.
claude plugin install은 다음과 같이 거부를 보고합니다:
claude plugin list는 플러그인을 failed to load로 표시합니다:
- 마켓플레이스를 유지하는 경우 항목의
source를./plugins/my-plugin과 같은 일반 상대 경로로 작성하고 이를 통과하는 모든 심볼릭 링크가 마켓플레이스 디렉터리 내부를 가리키도록 하십시오. - 마켓플레이스를 직접 URL에서 추가한 경우 상대 항목을 확인할 수 없습니다. 마켓플레이스 작성자에게 다른 플러그인 소스를 사용하도록 요청하거나 git 저장소에서 마켓플레이스를 추가하십시오.
Failed to load marketplace configuration
Claude Code는~/.claude/plugins/known_marketplaces.json의 레지스트리 파일에 추가한 플러그인 마켓플레이스를 유지합니다. claude plugin install과 같이 레지스트리가 필요한 플러그인 명령은 Claude Code가 파일을 사용할 수 없을 때 두 가지 메시지 중 하나로 실패합니다:
Failed to load marketplace configuration: 파일이 존재하지만 유효한 JSON이 아니거나 읽을 수 없습니다. 빈 파일도 이런 식으로 실패합니다.Marketplace configuration file is corrupted: 파일이 유효한 JSON이지만 내용이 레지스트리 스키마와 일치하지 않습니다.
claude plugin install은 다음을 보고합니다:
claude plugin install이 이 실패를 보고하지 않았습니다.
수행할 작업:
~/.claude/plugins/known_marketplaces.json을 열고 JSON을 복구하거나 메시지가 레지스트리 스키마와 일치하지 않는 것으로 이름을 지정한 항목을 수정하십시오.- 복구할 수 없으면 파일을 삭제하거나 내용을
{}로 바꾼 다음claude plugin marketplace add <source>로 각 마켓플레이스를 다시 추가하십시오. Claude Code는 신뢰한 폴더에서 다음에 시작할 때 사용자 또는 관리형 설정이extraKnownMarketplaces에서 선언한 마켓플레이스를 다시 등록합니다.
Plugin is required by your organization
claude plugin disable을 실행했거나 /plugin Installed 탭을 사용하여 조직이 필수로 표시한 claude.ai에서 동기화된 플러그인을 비활성화하려고 했습니다:
- claude.ai 조직의 관리자에게 claude.ai에서 플러그인의 필수 상태를 변경하도록 요청하십시오.
Plugin was not uninstalled
claude plugin uninstall을 실행했거나 /plugin Installed 탭에서 Uninstall을 선택했으며 제거가 "<plugin>" was not uninstalled:로 시작하는 메시지와 함께 중지되었습니다. 그 뒤의 텍스트가 설정 파일 이름을 지정하는 대신 installed_plugins.json으로 시작하면 원인은 이 버전의 Claude Code가 읽을 수 없는 installed_plugins.json의 내용입니다. 해당 형식의 경우 installed_plugins.json holds a record this version can’t read를 참조하십시오.
Claude Code가 enabledPlugins에서 플러그인의 항목을 제거하고 해당 범위의 설정 파일을 다시 읽었을 때 플러그인이 여전히 켜져 있었거나 이를 켤 수 있는 파일을 읽거나 확인할 수 없었습니다. 설정 항목이 이를 다시 켤 수 있는 동안 플러그인의 저장된 옵션, 비밀 및 데이터를 삭제하면 이를 잃게 되므로 제거가 대신 중지됩니다: 플러그인은 설치된 상태로 유지되고 저장된 것은 삭제되지 않습니다.
it is still switched on in <file>, although the settings change reported no error: 설정 쓰기가 성공을 보고했지만 파일을 읽을 때 항목이 여전히 있음it is still switched on in <file>, and the settings change failed (<error>): 파일을 저장할 수 없음. 괄호 안의 이유<file> is there and could not be read: 파일이 존재하지만 설정으로 읽을 수 없음. 예를 들어 유효한 JSON이 아니므로 플러그인을 여전히 활성화할 수 있음<file> (not read: it is on a network path or is a link to one, or could not be checked): Claude Code가 프로젝트 또는 로컬 설정 파일을 읽지 않았습니다. 파일 또는 이를 보유한.claude폴더가 네트워크 위치로 이어지는 링크이거나 해당 경로를 검사할 수 없기 때문입니다.
claude plugin uninstall은 종료 코드 1로 종료되며 --json을 사용하면 결과는 failureCode: "settings_still_on"을 전달합니다. /plugin은 동일한 메시지를 표시합니다.
수행할 작업:
- 메시지의 마지막 문장을 따르십시오: 이를 명명한 설정 파일을 복구하거나 바꾸거나 해당 파일의
enabledPlugins에서 플러그인의 항목을 직접 제거한 다음 제거를 다시 실행하십시오.
Skipping connection (recent failure cached; retries automatically in 15 min, or edit the plugin config to retry now)
이 메시지는 해당 서버에 대한 연결이 15분 이내에 실패했기 때문에 Claude Code가 플러그인이 제공하는 stdio MCP 서버를 시작하지 않았음을 의미합니다:claude -p 실행을 시작하면 Claude Code가 서버를 다시 시도합니다.
수행할 작업:
기다리지 않고 Claude Code가 서버를 다시 시도하도록 하려면:
- 대화형 세션에서:
/mcp를 실행하고 서버를 선택한 다음 Reconnect를 선택하십시오. - Agent SDK 애플리케이션에서: 서버 이름과 함께 TypeScript에서는
reconnectMcpServer()를, Python에서는ClaudeSDKClient.reconnect_mcp_server()를 호출하십시오. claude -p에서: 실행 시와 동일한 머신에서 동일한 운영 체제 계정과 동일한CLAUDE_CONFIG_DIR값으로 같은 플러그인을 로드하는 대화형 세션을 시작하십시오. 그곳에서/mcp를 통해 서버를 다시 연결하십시오. 연결되면 Claude Code는 다음 실행에서 연결을 시도합니다.- 플러그인을 개발하는 경우: 플러그인의
.mcp.json또는plugin.json에서 서버의command,args또는env를 변경하십시오. Claude Code는 변경된 항목을 로드하는 다음 세션 또는claude -p실행에서 연결을 시도합니다.
도구 오류
이 오류들은 Claude의 도구 호출에서 발생합니다. 대부분의 도구 오류는 Claude가 스스로 수정합니다. 사용자가 무언가를 변경해야 하는 경우에는 해당 오류의 조치 방법 목록에 변경할 내용이 안내되어 있습니다.No such tool available
Claude가 세션의 도구 목록에 없는 이름으로 도구를 호출했습니다. Claude Code는 이 오류를 도구 호출의 결과로 Claude에 반환하며, 턴은 계속 진행됩니다. Claude Code가 도구가 없는 이유를 파악할 수 있는 경우에는 두 번째 줄처럼 도구 이름 뒤에 이유를 설명하거나 대신 호출할 도구를 알려 주는 문장을 덧붙입니다.- 한 번만 발생했다면 별도로 조치할 필요가 없습니다. Claude가 오류를 읽고 턴이 계속 진행됩니다.
- MCP 서버의 도구 호출이 이 오류로 계속 실패한다면 세션에서
/mcp를 실행하거나 셸에서claude mcp list를 실행하여 서버의 상태를 확인하고, 실패한 서버는/mcp에서 다시 연결합니다. Agent SDK에서는 오류 처리를 참조하세요.
MCP server connection closed before the tool call was answered
HTTP MCP 서버 또는 claude.ai 커넥터에 대한 도구 호출이 서버가 응답하기 전에 연결이 끊겼기 때문에, Claude Code는 도구가 실행되었는지 알 수 없습니다.- 도구가 작업하는 서비스에서 작업이 실행되었는지 확인합니다. 예를 들어 생성하려던 이슈나 레코드가 있는지 확인합니다
- 작업이 실행되었다면 도구를 다시 실행하지 마세요. Claude는 도구의 결과 대신 이 메시지를 받았으므로 Claude에게 결과를 알려 줍니다.
- 작업이 실행되지 않았다면 Claude에게 도구를 다시 실행하도록 요청합니다. Claude Code가 해당 서버의 도구를 다음에 호출할 때 다시 연결하므로 서버를 먼저 다시 연결할 필요는 없습니다. 그 연결도 실패한다면 원격 서버의 세션 중 연결 끊김을 참조하세요.
- 서버를 직접 만들고 있고 해당 도구를 두 번 호출해도 안전하다면 Claude Code가 유실된 호출을 반복할 수 있도록 반복해도 안전한 것으로 표시합니다
MCP server is disabled
도구 결과에 이 메시지가 표시되면 Claude가 꺼져 있는 MCP 서버의 도구를 호출했다는 뜻입니다. Claude Code는 서버에 연결하지 않았으므로 도구는 실행되지 않았고, Claude는 결과 대신 다음 텍스트를 받았습니다.- 의도적으로 서버를 끈 것이라면 별도로 조치할 필요가 없습니다
- Claude가 서버의 도구를 사용해야 한다면 Claude Code 프롬프트에서
/mcp로 서버를 다시 켭니다 - Agent SDK 애플리케이션에서는 TypeScript의 경우
enabled를true로 설정하여toggleMcpServer()를 호출하고, Python의 경우enabled를True로 설정하여toggle_mcp_server()를 호출하여 서버를 다시 켭니다
서버의 질문에 답변이 없어 MCP 도구 호출이 시간 초과됨
비대화형 모드에서 MCP 서버가 도구 호출 중에 elicitation을 통해 입력을 요청했으나, 답변이 오기 전에 호출의 시간 제한이 끝났습니다.timed out after <N>s로 끝났으며 질문에 대해서는 아무것도 언급하지 않았습니다.
조치 방법:
- 서버의 요청에 답변하는
Elicitation훅을 설정합니다 - TypeScript Agent SDK 애플리케이션에서는
onElicitation콜백이 제한 시간이 끝나기 전에 답변을 반환하도록 합니다 - 답변할 시간을 더 주려면 서버의 구성 항목에서 더 긴
timeout을 밀리초 단위로 설정합니다. 예를 들어 10분이라면"timeout": 600000으로 설정합니다 - 대신 대화형 세션에서 작업을 실행하고 서버의 대화 상자에 직접 답변합니다
Permission prompt tool returned an invalid result
--permission-prompt-tool에 전달한 도구가 Claude Code가 읽을 수 없는 응답을 반환했기 때문에, 응답이 호출을 허용했더라도 그 응답을 기다리던 도구 호출은 실행되지 않았습니다.
- 텍스트가
{"behavior": "allow"}또는{"behavior": "deny", "message": "<reason>"}인 텍스트 블록 하나를 반환합니다. 입력을 변경하려면allow객체에updatedInput을 추가합니다. v2.1.86부터 v2.1.206까지는allow에서 입력을 유지하려면"updatedInput": {}가 필요했습니다. - MCP SDK가 자동으로 추가할 수 있는
structuredContent를 반환하지 않습니다. 예를 들어 도구를 다음과 같이 등록합니다.mcp.server의FastMCP또는MCPServer:structured_output=False로 등록합니다fastmcp의FastMCP:output_schema=None으로 등록하고 문자열을 반환합니다- MCP TypeScript SDK:
outputSchema없이 등록합니다
- 약 40KB 이상의 입력에서만 오류가 발생한다면 입력을
updatedInput이나 거부의message에 복사하지 마세요. 그렇게 큰 입력을 변경하려면 프롬프트 도구의 출력 제한을 높입니다.
Agent would be spawned with zero tools
서브에이전트의tools 목록에 있는 모든 항목이 사용 가능한 도구와 일치하지 않았기 때문에 Claude Code가 서브에이전트 실행을 거부했습니다. 도구가 없으면 서브에이전트는 아무 작업도 할 수 없습니다. 메시지는 항목을 문제 유형별로 분류합니다.
- Unrecognized: 항목이 어떤 도구 이름과도 일치하지 않습니다. 보통
Grep을Grpe로 쓴 것과 같은 오타입니다. - Not available to subagents: 항목이 실제 도구를 가리키지만 서브에이전트가 사용할 수 없는 도구입니다. 백그라운드 서브에이전트는 더 작은 내장 도구 세트를 유지하므로, 포그라운드 서브에이전트만 사용할 수 있는 항목은 서브에이전트가 기본값인 백그라운드에서 실행될 때 여기에 분류됩니다.
Agent를 나열한 경우에는 메시지가 대신 다음 그룹에서 이를 보고합니다. - Matched no tools in this session: 항목은 유효하지만 현재 세션에서 지금 일치하는 도구가 없습니다. 예를 들어 GitHub MCP 서버가 연결되지 않은 상태의
mcp__github__*나, 깊이 제한에 도달한 서브에이전트의Agent가 여기에 해당합니다.
tools 필드를 생략하면 이 거부가 발생하지 않습니다. tools 목록을 비워 두거나 disallowedTools가 그 안의 모든 항목을 제거하는 경우에도 Claude Code는 거부를 건너뛰고 도구 없이 서브에이전트를 실행합니다.
v2.1.208 이전에는 서브에이전트가 도구 없이 실행되어 빈 결과나 혼란스러운 결과를 반환할 수 있었습니다.
- 오류가 지목한 각 항목을 서브에이전트가 사용할 수 있는 도구와 대조하여 수정합니다
- 연결되지 않은 서버의 MCP 도구처럼 세션에 없는 도구의 항목은 제거합니다
- 항목이 연결된 MCP 서버를 가리킨다면, 항목을 해당 서버의 도구 이름에 표기된 서버 이름과 비교합니다. 예를 들어
mcp__reports__v2__get_totals에서는reports__v2입니다. 이 서버의 경우mcp__reports__v2__*, 즉mcp__뒤에 전체 이름과__*를 붙여 작성합니다.reports라는 서버를 가리키는 더 짧은mcp__reports를 사용하면 서브에이전트는reports__v2도구를 하나도 받지 못합니다 CronCreate처럼 백그라운드 서브에이전트에서 제외되는 도구의 경우 해당 항목을 제거합니다- 대신
CronCreate같은 도구를 유지하려면 Claude가 서브에이전트를 기다리도록 합니다. Claude가 기다리는 서브에이전트는 포그라운드에서 실행되며 해당 도구를 유지합니다. 정의에background: true가 설정되어 있다면 이 필드가 서브에이전트를 백그라운드에 머물게 하므로 먼저 해당 필드를 제거합니다 - 서브에이전트에게 서브에이전트가 사용할 수 있는 모든 도구를 제공하려면 도구를 나열하는 대신
tools필드를 삭제합니다 Agent만 포함된tools목록의 경우 깊이 제한을 높이거나 에이전트에게 다른 도구를 하나 이상 제공합니다. Claude Code는 해당 제한에서Agent를 제공하지 않으므로, 다른 항목이 없는 목록은 도구가 없는 것으로 처리됩니다
File is covered by a Read deny rule
Read 거부 규칙과 일치하는 경로에 대해 Edit 또는 Write 도구가 호출되었습니다. 해당 경로에 새 파일을 만드는 경우도 포함됩니다. 두 도구 모두 Claude가 다시 읽을 수 있어야 하는 콘텐츠를 변경하므로, Claude Code는 파일에 접근하기 전에 호출을 거부합니다. NotebookEdit은 Read 거부 규칙의 적용을 받지 않습니다. v2.1.228 이전에는 이 규칙이 Edit 도구만 차단했고, v2.1.208 이전에는 Edit 거부 규칙만 편집을 차단했습니다.
and cannot be written으로 끝납니다.
조치 방법:
- Claude가 파일을 변경할 수 있어야 한다면
/permissions또는 설정에서Read거부 규칙을 제거하거나 범위를 좁힙니다 - 파일을 그대로 유지해야 한다면 규칙을 유지하고, NotebookEdit 도구도 차단되도록 같은 경로에 대한
Edit거부 규칙을 추가합니다
Setting blocks writes outside the working directories
Claude가 파일을 쓰려고 할 때 도구 호출이 이 메시지와 함께 실패하면, 해당 경로가 세션의 작업 디렉터리 외부에 있고permissions.blockWritesOutsideWorkingDirectories가 켜져 있는 것입니다.
- Claude가 그 위치에 쓰면 안 된다면 아무것도 하지 않습니다
- 경로를 포함하는 기존 디렉터리에 Claude가 쓸 수 있도록 하려면 Claude Code 프롬프트에서
/add-dir <directory>를 실행하거나, Claude Code를 시작할 때--add-dir <directory>를 전달합니다 - 경로가
~/.claude/settings.json같은 Claude Code 설정 파일이라면 직접 편집합니다./add-dir로 해당 디렉터리를 추가해도 도움이 되지 않습니다. 그러면 Claude Code가 설정 파일이라는 이유로 쓰기를 거부하기 때문입니다. - 모든 세션에서 디렉터리를 쓰기 가능하게 유지하려면 사용자 설정 또는 관리형 설정의
permissions.additionalDirectories아래에 해당 디렉터리를 나열합니다 permissions.blockWritesOutsideWorkingDirectories를 끄려면 이를 설정하는 모든 설정 파일에서 제거한 다음 Claude Code를 다시 시작합니다- 사용자의 설정 파일 중 어디에도
permissions.blockWritesOutsideWorkingDirectories가 없다면--settings또는 호스트 애플리케이션에서 온 설정일 수 있습니다. Claude Code는 관리형 설정의permissions를 읽을 수 없는 동안에도 이러한 쓰기를 거부합니다. 세션을 시작하거나 관리하는 담당자에게 문의하세요.
Writes to Claude Code settings files are blocked
Claude가 파일을 쓰려고 할 때 도구 호출이 이 메시지와 함께 실패하면, Claude Code가 해당 파일을 자신의 설정 파일 중 하나로 취급하고 있으며permissions.blockWritesOutsideWorkingDirectories가 켜져 있는 것입니다.
- 설정을 변경하려면 설정 파일을 직접 편집합니다
- Claude가 다시 설정 파일을 편집할 수 있도록 하려면
permissions.blockWritesOutsideWorkingDirectories를 설정하는 모든 설정 파일에서 이를 제거한 다음 Claude Code를 다시 시작합니다 - 해당 파일이 사용자의 설정 파일이 아니라면 Claude Code가 설정 파일로 취급하는 다른 파일 중에서 찾습니다.
--agents또는--mcp-config에 전달한 파일: 직접 편집합니다- 서버 관리형 설정의 저장된 사본 및 함께 보관되는 파일: Owner에게 서버 관리형 설정에서 해당 설정을 변경하도록 요청합니다.
- Claude Code가
managed-settings.d/폴더가 어디로 이어지는지 파악할 수 없는 동안의 모든.json파일: 관리자에게 해당 폴더를 확인하도록 요청합니다
Path cannot contain null bytes
파일 도구 호출의 경로 또는 패턴 인수에 파일 시스템과 검색 도구가 허용하지 않는 null 바이트가 포함되어 있었습니다. Read, Write, Edit, NotebookEdit, Glob, Grep이 이를 검사하며, 메시지에는 도구와 인수가 표시됩니다.- 사용자 측에서 할 일은 없습니다. 오류는 도구의 결과로 Claude에 반환되며, 메시지 자체가 Claude에게 null 바이트를 제거하고 다시 시도하라고 안내합니다
Path contains null bytes를 언급하는 오류와 함께 턴 전체가 종료되었고, 도구는 실행되지 않았습니다.
Command contains an invisible character
PowerShell 도구가 U+FEFF 또는 U+180E가 포함된 명령의 실행을 거부했습니다.- Claude가 작성한 명령의 경우: 수정할 것이 없습니다. 메시지가 Claude에게 명령을 다시 작성하는 방법을 알려 줍니다.
- 스킬 또는 명령 파일의 경우: 메시지는
No shell command in <name> was run뒤에 표시됩니다. 문자를 찾아 제거하는 위치를 참조하세요.
Claude Code 재시작 후 승인된 명령이 실행되지 않음
사용자가 승인한 셸 명령이 실행되지 않았으며, Claude는 명령의 결과로 다음 메시지를 받습니다.It does not keep track of that directory across a restart in a session that has been in a worktree.로 표시될 수 있습니다.
조치 방법:
- Claude가 계속 진행하도록 두고, 명령을 다시 승인하라는 요청을 받으면 프롬프트에 응답합니다.
File is too large to read as an image
Claude가 Read 도구로 파일을 이미지로 읽으려 했지만, 파일이 Read가 이미지 파일에서 불러올 수 있는 최대 크기인 128MB보다 큽니다. 아무것도 읽히지 않았으며, Claude는 도구 결과로 다음 오류를 받습니다.- Claude가
File is too large메시지에 따라 이미지 크기를 조정하거나 더 작은 사본을 읽었다면 별도로 조치할 필요가 없습니다 - Claude가 오류에서 멈췄다면 더 낮은 해상도 등으로 128MB 미만의 사본을 직접 내보낸 다음 Claude에게 해당 파일을 지정합니다
- 경로가 파이프나 디바이스였다면 대신 일반 이미지 파일을 Claude에게 지정합니다
subagent_type is required
subagent_type 없이 Agent 도구를 호출했는데, 이 세션에는 대체로 사용할 범용 서브에이전트가 없습니다. 이는 다음 두 가지 설정에서 발생합니다.
- 비대화형 모드에서
CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1이 설정되어 모든 내장 서브에이전트가 제거된 경우 - 세션의 메인 스레드 에이전트에
general-purpose를 제외한tools: Agent(...)허용 목록이 있는 경우
- 보통은 조치할 필요가 없습니다. 메시지에 세션에서 사용할 수 있는 서브에이전트가 나열되므로 Claude가 그중 하나로 재시도할 수 있습니다
- Claude가 계속 실패한다면
tools: Agent(...)허용 목록에general-purpose를 추가하거나CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS설정을 해제합니다
Agent type 'general-purpose' not found로 실패했습니다.
메모리 인덱스가 읽기 제한을 초과함
Claude가 자동 메모리 인덱스MEMORY.md에 쓰기를 수행했고, 그 결과 파일이 읽기 제한인 200줄 또는 25KB 중 하나를 초과했습니다. 쓰기는 성공했지만 세션 시작 시 처음 200줄 또는 25KB 중 먼저 도달하는 분량만 로드되므로, 인덱스를 읽을 때마다 제한을 넘는 내용은 모두 누락됩니다. v2.1.210 이전에는 제한을 초과한 인덱스가 쓰기 시점에 아무런 신호 없이 다음 로드 시 조용히 잘렸습니다.
- Claude가
MEMORY.md를 다시 작성하도록 두거나 요청합니다. 항목당 한 줄을 유지하고, 세부 내용은 주제 파일로 옮기고, 오래된 항목은 병합하거나 삭제합니다 - 인덱스를 직접 정리하려면 메모리 감사 및 편집을 참조하세요
pkill 패턴이 Claude Code 프로세스와 일치함
Bash 도구 호출의pkill 명령이 보통 -f와 함께 Claude Code 프로세스 자체와 일치하는 패턴을 사용했기 때문에, Claude Code는 해당 명령이 세션을 종료하도록 두지 않고 명령을 거부합니다. Claude Code는 pkill을 실행하기 전에 pgrep으로 패턴을 테스트하고, 결과에 자신의 프로세스 ID가 있으면 거부합니다. 이 검사는 Linux에서만 실행되며, macOS에서는 pkill이 수정 없이 실행됩니다. v2.1.214 이전에는 명령이 실행되어, 일치하는 패턴이 턴 도중에 Claude Code 세션을 종료시켰습니다.
- 짧은 부분 문자열 대신 대상 바이너리의 전체 경로를 사용하는 등 의도한 프로세스만 일치하도록 패턴을 좁힙니다
- 현재 셸이 시작한 프로세스를 중지하려면 패턴과 함께
pkill -P $$를 사용합니다. 이렇게 하면 일치 대상이 셸 자신의 자식 프로세스로 제한됩니다
Failed to write to a teammate’s inbox
Claude Code가~/.claude/teams/{team-name}/inboxes/ 아래에 있는 팀원의 메일함 파일에 메시지를 쓰지 못했으므로 수신자는 아무것도 받지 못했습니다. 디스크가 가득 찼거나, 디렉터리에 쓰기 권한이 없거나, 다른 에이전트가 받은 편지함 잠금을 너무 오래 점유하는 등의 이유로 Claude Code가 파일을 생성하거나 업데이트할 수 없을 때 쓰기가 실패합니다. v2.1.224 이전에는 쓰기가 실패해도 Claude Code가 메시지를 전송된 것으로 보고했습니다.
오류는 터미널의 배너가 아니라 보낸 에이전트의 도구 결과에 표시되며, 오류 텍스트가 Claude에게 다시 시도하라고 안내합니다.
Failed to write the <message> to <name>'s inbox — nothing was sent로 표시됩니다. 이 목록의 plan approval은 팀원의 플랜을 승인하는 리드의 결정이며, 팀원의 플랜 제출은 별도의 plan approval request 메시지입니다. 이 메시지와 다른 두 프로토콜 메시지는 각각 고유한 메시지 텍스트와 결과를 가집니다.
Failed to write the plan approval request to the lead's inbox — plan not submitted; try again: 팀원의 플랜이 리드에게 전달되지 않았으며, 재제출이 성공할 때까지 팀원은 플랜 모드에 머뭅니다The permission request could not be delivered to the team lead (mailbox write failed): 팀원의 권한 요청이 리드에게 전달되지 않았으므로 아무도 도구 호출을 승인하지 않았습니다The confirmation could not be written to team-lead's inbox.: 종료 승인 자체는 적용되어 팀원이 종료됩니다. 리드에게 보내는 확인만 누락되었습니다
@name 뒤에 메시지를 입력하여 팀원에게 직접 메시지를 보내는 경우, 같은 실패가 Couldn't write to @name's inbox — message not sent. Try again. 알림으로 표시되며, Claude Code는 다시 보낼 수 있도록 입력한 텍스트를 프롬프트 상자에 유지합니다.
조치 방법:
- 보낸 쪽에 메시지를 다시 보내도록 요청합니다. 받은 편지함 잠금 경합은 일시적이며 재시도하면 해결됩니다
- 여유 디스크 공간을 확인하고,
~/.claude/teams와 그 아래 파일에 사용자 계정의 쓰기 권한이 있는지 확인합니다
Teammate’s agent definition was not restored
Claude가 중지된 에이전트 팀 팀원에게 메시지를 보냈고, Claude Code는 팀원을 생성할 때 사용한 서브에이전트 정의를 다시 적용하지 않고 팀원을 복귀시켰습니다. 이 알림은 보낸 에이전트의 도구 결과에서 재개 보고 뒤에 표시되며 이유를 알려 줍니다. 정의 파일이 신뢰가 저장되지 않은 폴더에서 온 경우 다음과 같이 표시됩니다.--add-dir 디렉터리의 .claude/agents/ 디렉터리에 있는 정의에 적용되며, 상위 폴더에 대한 신뢰 대화 상자를 수락해도 충족되지 않습니다.
조치 방법:
- 디버그 로그에 표시된 폴더에서
claude를 실행하고 신뢰 대화 상자를 수락합니다. 다음에 Claude Code가 팀원을 복귀시킬 때 정의가 다시 적용되며, 리드 세션을 다시 시작할 필요는 없습니다 - 또는 디버그 로그에 출력된 정확한
projects["<path>"]키를 사용하여~/.claude.json에서hasTrustDialogAccepted항목을true로 설정합니다
Only a teammate can approve a shutdown request
전송한 세션이 팀원으로 실행 중이 아니기 때문에 Claude Code가 에이전트 팀 종료 승인을 거부했습니다. 아무것도 전송되지 않았고 아무것도 종료되지 않았습니다. 거부는 전송한 세션의 도구 결과에 표시됩니다.- 리드 세션에 거부가 표시되었다면 먼저 그 사이에 팀원이 종료되었는지 확인합니다. 거부는 대신
shutdown_request를 보내라는 지시와 함께 Claude에 반환되며, 턴은 계속 진행됩니다. 대화형 리드 세션에서는 팀원이 종료 요청을 승인하면<name> has shut down.이 표시됩니다. - 팀원이 아직 실행 중이라면 리드의 프롬프트에서 팀원을 종료하도록 요청합니다. 예:
Ask the researcher teammate to shut down. 팀원 종료를 참조하세요. claude --resume으로 직접 재개한 이전 팀원이 이 거부를 받았다면 아무것도 전송되지 않았습니다. 해당 세션을 종료하려면 그 프롬프트에서/exit를 실행합니다.
A command-line deny rule cannot be handed to a teammate intact
이 메시지는 Claude Code가 에이전트 팀에서 분할 창 팀원을 시작하지 않았다는 뜻입니다. Claude Code는 리드의 명령줄 거부 규칙을 분할 창 팀원 자체의 명령줄로 전달하며, 팀원이 그중 하나를 다르게 해석하게 될 경우 중단합니다.- 리드 세션에서
/config를 실행하고 Teammate mode를in-process로 설정합니다. 해당 행에overridden이 표시되고 이미in-process가 표시되어 있다면 값을 순환하여 다시in-process로 돌아오게 합니다. 그런 다음 Claude에게 팀원을 다시 시작하도록 요청합니다. 인프로세스 팀원은 리드의 실시간 거부 규칙에 따라 실행됩니다. /config는 선택 사항을 사용자 설정에 저장하므로, 사용자 설정에서teammateMode를 가져오는 이후 세션도 팀원을 인프로세스로 시작합니다. 이후 세션에서 분할 창으로 돌아가려면 Teammate mode를 이전에 사용하던auto,tmux또는iterm2중 하나로 설정합니다.
Message too large for cross-session delivery
이 머신의 다른 세션으로 보낸 Claude의 세션 간 메시지가 너무 길어서 전송할 수 없었습니다. Claude Code가 이를 거부했으며, 수신 세션은 아무것도 받지 못했습니다. 거부는 터미널의 배너가 아니라 전송한 세션의 도구 결과에 표시됩니다. 거부 메시지에는 두 크기와 메시지를 제한에 맞추는 방법이 표시됩니다.- Claude에게 메시지를 요약하거나, 대용량 콘텐츠를 파일에 넣고 파일 경로를 보내도록 요청합니다
- Claude에게 콘텐츠를 여러 개의 짧은 메시지로 나누도록 요청합니다
Too many messages to this session just now
Claude가 이 머신의 세션 중 하나에 세션 간 메시지를 짧은 시간에 연달아 보냈고, 그 양이 해당 세션의 받은 편지함이 수용하는 한도에 도달했습니다. Claude Code는 다음 전송을 거부했으며, 수신 세션은 그 메시지를 받지 못했습니다. 거부는 터미널의 배너가 아니라 전송한 세션의 도구 결과에 표시됩니다.- 보통은 조치할 필요가 없습니다. Claude가 남은 콘텐츠를 하나의 메시지로 묶거나, 잠시 기다린 후 더 보냅니다
- 연속 전송을 직접 요청했다면 Claude에게 남은 내용을 하나의 메시지로 합치도록 요청합니다
Cross-session message was dropped at the recipient session’s inbox
Claude가 이 머신의 다른 세션에 세션 간 메시지를 보냈지만, 해당 세션의 Claude가 읽기 전에 그 세션의 받은 편지함이 메시지를 폐기했습니다. 이 줄에는 수신자가 표시되며, 수신자가 이유를 제공한 경우 대시 뒤에 이유가 추가됩니다.Cross-session messages (12) were dropped처럼 복수형으로 시작합니다. 주소가 어느 세션에 속하는지 확인하려면 각 세션에서 /status가 표시하는 Peer address 행과 비교합니다.
대시 뒤에는 다음 이유 중 하나 이상이 표시됩니다.
its queue of undelivered peer messages was full: 수신자가 이미 큐가 허용하는 만큼의 다른 세션 미전달 메시지를 보유하고 있었습니다you sent faster than that session accepts: 전송한 세션의 메시지가 수신자가 한 발신자로부터 받아들이는 속도보다 빠르게 도착했습니다it repeated your previous message: 메시지가 전송한 세션이 직전에 이 수신자에게 보낸 메시지와 동일했습니다a relay loop between sessions was cut: 메시지가 이 머신 외부의 세션을 포함하는 연쇄처럼 끊길 수 있는 긴 응답 연쇄를 이어 갔습니다
- 수신자가 폐기된 메시지를 보지 못했다고 가정합니다. Claude Code도 Claude에게 같은 내용을 알리며, 즉시 다시 보내는 대신 여전히 중요한 내용을 이후 메시지 하나에 포함하라고 안내합니다
- 세션들이 서로 업데이트를 자주 보낸다면 Claude에게 세션이 작업을 마쳤을 때 보고서 하나를 보내는 식으로 더 적고 큰 메시지를 보내도록 요청합니다
a relay loop between sessions was cut의 경우 세션 중 하나에 다음 지시를 직접 입력합니다. 사용자의 프롬프트에 대한 응답으로 Claude가 보내는 메시지는 새로운 연쇄를 시작합니다
세션 간 메시지 전송 거부
Claude Code는 이 머신의 다른 세션에 세션 간 메시지를 쓰기 전에, 대상 세션의 받은 편지함 소켓이 메시지가 지정된 엔드포인트인지 확인합니다. 검사가 실패하면 Claude Code는 전송한 세션에서 전송을 거부하며, 대상 세션은 아무것도 받지 못합니다. Claude가 보내는 메시지의 경우 거부는 전송한 세션의 도구 결과에 표시됩니다.Refusing to send: 뒤의 텍스트는 실패한 검사를 나타냅니다.
reply target is a symlink: 대상 세션의 소켓 경로에 심볼릭 링크가 있습니다. 그 위치의 링크가 대상 세션이 만들지 않은 엔드포인트로 메시지를 리디렉션할 수 있으므로 Claude Code는 이를 통해 전달하지 않습니다.cannot vet reply target: 대상 경로를 읽는 중 권한 오류가 발생하는 등의 이유로 Claude Code가 대상 경로를 전혀 검사할 수 없었습니다.
- 보통은 조치할 필요가 없습니다. 이 검사는 메시지가 지정된 세션 이외의 엔드포인트에 도달하지 않도록 하며, 아무것도 전송되지 않았습니다
- 한 세션에서
reply target is a symlink가 반복된다면 해당 세션의/status에서Peer address아래에 표시되는 소켓 경로에 무엇이 링크를 만들었는지 확인합니다
경로 읽기, 쓰기 또는 검색 거부
Claude Code는 파일 경로의 권한 규칙을 확인한 다음, 도구가 파일을 열거나 검색을 시작할 때 경로 해석을 다시 확인합니다. 경로가 여전히 검사에서 승인된 위치로 이어지는지 확인할 수 없으면 Claude Code는 그 경로를 따라가는 대신 작업을 거부합니다. 거부는 도구 결과에 표시됩니다.its symlink resolution changed after permission was checked: 권한 검사와 작업 사이에 경로상의 심볼릭 링크 또는 Grep이나 Glob 검색 루트의 심볼릭 링크가 교체되었습니다. 읽기 거부에서는 괄호 안의 문구가 어떤 비교가 실패했는지 알려 줍니다.its parent-directory symlink resolution changed after permission was checked: 쓰기 경로가 거치는 디렉터리가 더 이상 승인된 위치로 해석되지 않습니다where it leads on disk could not be determined (a link on the way could not be examined, or the links do not resolve): 경로상의 심볼릭 링크가 루프를 형성하는 등의 이유로 Claude Code가 경로를 디스크상의 최종 위치까지 따라갈 수 없었습니다it is a symbolic link. Write to the link's target path instead:AGENTS.md에 대한 심볼릭 링크인CLAUDE.md처럼 요청된 쓰기 위치 자체에 심볼릭 링크가 있습니다. 메시지는 Claude에게 링크의 대상을 안내합니다Refusing to write through symlink: <path>. Resolve the symlink and pass the real target path explicitly.: 심볼릭 링크된.mcp.json에 쓰는 경우처럼 다른 쓰기 주체가 파일을 열 때 감지된 같은 상황입니다Refusing to write into symlinked directory: <path>: 다른 위치에 링크된 프로젝트의.claude/디렉터리처럼 파일을 담고 있는 디렉터리 자체가 심볼릭 링크입니다a path one of its Read deny rules is written through changed while the search was being prepared. Retry.: 검색에 대한Read거부 규칙이 심볼릭 링크를 거치는 경로를 지정하며, Claude Code가 검색을 준비하는 동안 그 링크가 변경되었습니다it could not be opened (EACCES) — it is unreadable, or is being replaced concurrently.: 검색 루트는 존재하지만 열 수 없었습니다. 괄호 안의 코드는 운영 체제 오류입니다its permission check expired before it ran (too many concurrent file operations). Retry.: 동시에 많은 파일 작업이 수행되는 상황에서 도구가 사용하기 전에 Claude Code가 승인 기록을 제거했습니다. 재시도하면 새로운 권한 검사가 실행됩니다ripgrep was found only by name on PATH, and a search outside the working directory cannot apply your Read deny rules in that configuration: Claude Code가rg바이너리를 절대 경로로 해석할 수 없었기 때문에, 거부 규칙이 적용되지 않는 검색을 실행하는 대신 작업 디렉터리 외부의 검색을 거부합니다
- 보통은 조치할 필요가 없습니다. 거부는 도구 결과로 Claude에 전달되며, 거부된 작업은 실행되지 않습니다
- 한 경로에서 심볼릭 링크 거부가 반복된다면 빌드 도구나 파일 감시자처럼 그 위치의 링크를 계속 다시 쓰는 주체를 찾거나, Claude에게 링크된 경로 대신 파일의 해석된 경로를 사용하도록 요청합니다
- Windows에서 AppContainer 또는 제한된 토큰 샌드박스 안에서 Claude Code를 실행할 때 모든 파일에 대해 이 거부가 표시된다면 v2.1.265 이상으로 업그레이드합니다
- macOS에서 프롬프트에 끌어다 놓은 스크린샷처럼 아무것도 다시 쓰지 않는 파일에 대해 읽기 거부가 표시된다면 v2.1.273 이상으로 업그레이드합니다
- ripgrep 거부의 경우
rg가PATH에서 절대 경로로 해석되도록 패키지 관리자로 ripgrep을 설치하거나, 검색을 작업 디렉터리 아래로 유지합니다
where it leads on disk could not be determined 거부가 표시되지 않았습니다.
The search failed, so this is not a “no matches” result
Claude가 실행한 Grep 또는 Glob 검색이 결과를 반환하기 전에 실패했으므로, 일치 항목이 있는지 알 수 없습니다. Claude가 결과 대신 받는 메시지는 다음과 같이 시작합니다.- 처음 나타난 경우: 조치할 필요가 없습니다. 메시지가 Claude에게 먼저 다시 검색하라고 요청합니다.
- Claude가 검색이 실패하고 있다고 알리는 경우: 버그 보고를 위해 ripgrep의 오류를 수집합니다.
- 셸에서 검색이 실패한 세션과 같은 플래그에
--debug-file claude-debug.log를 추가하여 세션을 시작합니다 - 검색 실패로 이어진 요청을 Claude에게 보냅니다
- 검색이 다시 실패하면
claude-debug.log에서rg error (signal=이 포함된 줄을 찾습니다 - 문제를 보고할 때 해당 줄을 포함합니다
- 셸에서 검색이 실패한 세션과 같은 플래그에
Task output swap refused
Claude Code는 각 Bash 명령의 출력을 임시 디렉터리 아래의 파일에 저장합니다. 이러한 파일을 열 때마다 심볼릭 링크, 추가 하드 링크 또는 이동된 디렉터리가 경로를 리디렉션하지 않고 경로가 여전히 자신이 만든 파일로 이어지는지 확인합니다. 이 메시지는 해당 검사가 실패했다는 뜻이므로, Claude Code는 그 경로를 통해 출력을 쓰거나 읽는 대신 작업을 거부했습니다. 메시지는 Bash 도구 결과에 표시됩니다.output symlink was re-pointed, output file identity changed, not a regular file 같은 이유는 모두 같은 상황을 보고합니다. 즉, 출력 경로 자체 또는 그 경로상의 무언가가 더 이상 Claude Code가 만든 파일이 아닙니다. 일부 이유에만 To recover: 문장이 포함됩니다.
명령이 아직 실행 중일 때 검사가 실패하면 Claude Code는 명령을 중지하며, 결과에 다음과 같이 보고됩니다.
- v2.1.260 이상으로 업그레이드합니다. 이전 버전에서는 링크나 이동된 디렉터리가 없을 때도 이 메시지가 표시되는 경우가 있었습니다
CLAUDE_CODE_TMPDIR를 새 디렉터리로 설정하여 Claude Code를 다시 시작합니다- 또는 Claude Code 임시 디렉터리 아래의 프로젝트 디렉터리를 확인합니다. 예시 메시지에서는
/private/tmp/claude-501/-Users-you-my-project입니다. 해당 경로가 심볼릭 링크이거나 있어서는 안 되는 디렉터리라면 링크의 대상이 아닌 링크나 디렉터리 자체를 제거하고 Claude Code를 다시 시작합니다 - 거부가 반복된다면 세션이 실행되는 동안 어떤 프로세스가 Claude Code 임시 디렉터리 아래의 항목을 교체, 링크 또는 제거하고 있는 것입니다.
CLAUDE_CODE_TMPDIR를 다른 어떤 것도 관리하지 않는 디렉터리로 설정하고 다시 시작합니다
Disk full or disk quota used up
Claude Code의 임시 디렉터리가 있는 볼륨에서 공간, inode 또는 디스크 할당량을 확보합니다. 명령 결과에서Disk full:, Disk quota used up: 또는 Nearly out of inodes:로 시작하는 줄에 해당 디렉터리가 표시됩니다.
Claude Code는 각 Bash 및 PowerShell 명령의 출력을 해당 디렉터리 아래의 파일에 저장합니다. 볼륨 또는 해당 볼륨의 사용자 할당량이 가득 차서 이 파일을 만들 수 없으면 명령이 시작되지 않으며, Claude가 읽는 결과는 다음과 같습니다.
Disk full:, Disk quota used up:, Nearly out of inodes: 메시지는 실행된 후 0이 아닌 코드로 종료된 명령 뒤에 표시됩니다. 예:
- macOS와 Linux에서는 셸에서
df -h <dir>를 실행하여 어떤 볼륨에 디렉터리가 있으며 얼마나 찼는지 확인합니다.df -i <dir>는 사용 가능한 inode 수를 보여 줍니다.<dir>는 메시지에 표시된 디렉터리이며, 예를 들어df -i /tmp/claude-501처럼 사용합니다 Disk full: this computer's volume또는disk is full (ENOSPC): 해당 볼륨의 아무 위치에서나 필요 없는 파일을 삭제합니다Disk quota used up:,disk quota is used up (EDQUOT)또는Disk full: a test write: 볼륨에 여유 공간이 있는 것으로 표시되더라도 해당 볼륨에서 사용자 본인의 파일을 삭제합니다Nearly out of inodes:: 해당 볼륨에서 많은 파일을 삭제합니다. 파일은 크기와 관계없이 각각 inode 하나를 차지하므로, 크기가 아니라 파일 개수가 중요합니다- 또는
CLAUDE_CODE_TMPDIR를 여유 공간이 있는 볼륨의 디렉터리로 설정하여 Claude Code를 다시 시작합니다 - 그런 다음 Claude에게 명령을 다시 실행하도록 합니다
Your disk quota is full on the filesystem with Claude Code's temp directory <dir> (EDQUOT)The filesystem with Claude Code's temp directory <dir>, or your disk quota on it, is full (ENOSPC)Command output was lost: the temp filesystem at <dir> is full또는... is out of inodesThe command was not started: this computer's disk is full (ENOSPC), so the file that captures command output could not be created. Nothing ran.또는(EDQUOT)가 포함된 같은 메시지. 이 형식에는 디렉터리가 표시되지 않으므로/tmp같은 시스템 임시 디렉터리 또는CLAUDE_CODE_TMPDIR에 설정된 디렉터리가 있는 볼륨을 확인합니다
ENOSPC: no space left on device, open <path>.output과 같았습니다.
git is not installed on this Mac
이 메시지는 Claude Code의 어떤 단계에 git이 필요했는데, 찾은 git이/usr/bin/git에 있는 Apple의 대체 실행 파일이라는 뜻입니다. git을 제공하는 개발자 도구가 설치되어 있지 않습니다.
Claude Code는 대체 실행 파일을 시작하지 않고 대신 이 텍스트를 표시하며, 예를 들어 더 긴 메시지 안에 포함될 수 있습니다.
- 터미널에서
xcode-select --install을 실행하고, 시작된 설치를 완료한 다음, Claude Code에서 하던 작업을 다시 시도합니다
File is not valid UTF-8
Claude가 바이트를 UTF-8로 디코딩할 수 없는 파일에 Edit 또는 NotebookEdit 도구를 사용했고, Claude Code가 변경을 거부했습니다. 아무것도 쓰이지 않았으므로 파일은 그대로입니다. 이 도구들은 파일 전체를 UTF-8로 다시 저장하므로, 디코딩할 수 없는 모든 바이트가 대체 문자U+FFFD로 바뀌었을 것입니다. 메시지는 도구 결과에 표시됩니다.
- 파일을 현재 인코딩으로 유지하려면 메시지의 안내대로 Claude가 해당 인코딩으로 파일을 읽고 쓰는 셸 명령으로 변경하도록 합니다
- Edit 도구로 파일을 계속 편집하려면 파일을 UTF-8로 변환하거나, UTF-8로 의도된 파일이라면 잘못된 바이트를 수정한 다음, Claude에게 편집을 다시 하도록 요청합니다
U+FFFD로 저장했습니다. 해당 버전을 사용 중이라면 Claude Code를 업데이트합니다.
Refusing to apply edits: a hook is configured for file edits in this session
Claude가 한 단계 업데이트로 아티팩트를 게시하려 했지만 Claude Code가 거부했습니다. 한 단계 업데이트는 게시에 포함된 아티팩트 파일의 작은 변경입니다. 아무것도 게시되지 않았으며 파일은 변경되지 않았습니다. 메시지는 Artifact 도구 결과에 표시됩니다.Edit 또는 Write에 대한 PreToolUse 훅이나 mod가 있는 동안에는 한 단계 업데이트를 허용하지 않습니다.
조치 방법:
- Claude가 이어서 파일을 편집하고 게시했다면 조치할 필요가 없습니다
- Claude가 메시지에서 멈췄다면 Claude에게 파일을 편집하고 게시하도록 요청합니다
- 메시지가 계속 나타난다면 Claude Code를 종료하고 다시 실행합니다
- 다시 실행한 후에도 메시지가 나타난다면 한 단계 업데이트를 끕니다
The source file is not valid UTF-8 text
Claude가 바이트를 텍스트로 디코딩할 수 없거나 텍스트에 이미 대체 문자U+FFFD가 포함된 파일에서 아티팩트를 게시하려 했기 때문에, Claude Code가 아무것도 업로드하기 전에 게시를 거부했습니다. 메시지는 Artifact 도구 결과에 표시되며 수정해야 할 첫 번째 위치를 알려 줍니다.
UTF-16이 표시되며, 여전히 파일을 UTF-8로 다시 작성하라고 안내합니다. 표시된 위치 뒤에 더 많은 위치가 있으면 메시지는 위치 뒤에 (+2 more) 같은 개수를 추가합니다.
조치 방법:
- 보통은 조치할 필요가 없습니다. Claude가 파일을 다시 작성하고 다시 게시합니다
- 직접 작성하거나 내보낸 파일이라면 UTF-8로 다시 저장하고, 각
U+FFFD를 이전 편집, 붙여넣기 또는 변환에서 손실된 문자로 바꿉니다 - 페이지에 의도적으로
U+FFFD를 표시하려면 HTML에서 리터럴 문자 대신�로 작성합니다
Not published: that file is on a network share
Claude가 네트워크 호스트를 지정하는 경로의 파일에서 아티팩트를 게시하려 했습니다.- Windows의 경우, 시작 시
--add-dir로 전달한 매핑된 네트워크 드라이브 아래에 있지 않은\\server\share경로 - macOS 또는 Linux의 경우,
/net/<host>/page.html같은 자동 마운트 경로
- 그 파일이 꼭 필요한 것이 아니라면 조치할 필요가 없습니다. 메시지가 Claude에게 대신 세션의 폴더에 있는 파일을 게시하라고 안내합니다
- 그 파일을 그대로 게시하려면 로컬 디스크의 폴더로 복사한 다음 다시 요청합니다
- Windows에서 Claude가 공유 위치에서 직접 게시할 수 있도록 하려면 공유 위치를 드라이브 문자에 매핑하고 Claude Code를 시작할 때 해당 드라이브를 전달합니다. 예를 들어 PowerShell에서
net use Z: \\server\share를 실행한 다음claude --add-dir Z:\를 실행합니다. 그러면 Claude가 해당 드라이브의 파일을 게시할 수 있습니다. 세션 도중/add-dir로 드라이브를 추가하는 것만으로는 충분하지 않습니다. - macOS 또는 Linux에서는
/mnt또는/Volumes아래 디렉터리 같은 곳에 공유 위치를 마운트하고, 자동 마운트 경로 대신 해당 경로에서 게시합니다
Not published: Claude sent the same content again after a newer version of the artifact turned it away
Artifact 호출 아래의 이 빨간 줄은 Claude Code가 반복된 게시를 중단했다는 뜻입니다. 아티팩트는 업데이트되지 않았으며, Claude가 게시하는 원본 파일에도 아무것도 쓰이지 않았습니다. Claude가 게시하지 않고 멈춘 경우에만 조치가 필요하며, 그렇지 않다면 별도로 조치할 필요가 없습니다. 세션 초반에 아티팩트에 더 새로운 버전이 있었기 때문에 Claude Code가 게시를 거부했습니다. 예를 들어 편집자 또는 사용자의 다른 세션이 게시한 버전이 있었던 경우입니다. 줄의 끝부분은 Claude가 다음에 해야 할 일을 알려 줍니다.Claude needs to work from that newer version first로 끝나는 경우: Claude가 거기서 멈췄다면 아티팩트의 현재 버전을 가져와 변경 사항을 병합한 다음 다시 게시하도록 요청합니다should go through로 끝나는 경우: Claude가 거기서 멈췄다면 다시 게시하도록 요청합니다
Cowork 세션에서 연결된 폴더 외부의 로컬 파일 읽기
Claude Desktop 앱에서 사용자의 머신으로 실행되는 Cowork 세션에서 Claude가 아티팩트에 사용할 로컬 파일을 지정했습니다. Claude Code는 해당 파일이 세션의 연결된 폴더 안에 있는 일반 파일인지 확인할 수 없었습니다. 경로가 해당 폴더 외부에 있거나, 심볼릭 링크를 거치거나, 겉보기와 다른 파일을 가리킬 수 있는 방식으로 작성되어 있습니다. 이러한 파일을 읽으려면 사용자의 승인이 필요하며, 모든 승인을 건너뛰도록 설정된 세션처럼 승인 카드를 표시할 수 없는 세션에서는 Claude Code가 읽기를 거부합니다. 거부는 Artifact 도구 결과에 표시되며, 파일을 전혀 검사할 수 없었던 경우에는 대신 그 실패를 알려 줍니다.- 보통은 조치할 필요가 없습니다. 메시지가 Claude에게 대신 연결된 폴더 안의 일반 파일을 사용하라고 안내합니다
- 그 파일을 그대로 아티팩트에 넣으려면 심볼릭 링크가 아닌 일반 파일로 세션의 연결된 폴더 중 하나에 복사한 다음 다시 요청합니다
WebFetch cannot fetch localhost
Claude가http://localhost:3000이나 http://wiki/ 같은 단순 인트라넷 이름처럼 호스트 이름에 점이 없는 URL로 WebFetch를 호출했습니다. WebFetch는 요청을 보내기 전에 이러한 URL을 거부합니다.
- 보통은 조치할 필요가 없습니다. 메시지가 Claude에게 로컬 및 인트라넷 서버에 접근할 수 있는 Bash 도구를 통한
curl을 안내합니다
Invalid URL 오류로 보고했습니다.
Claude Code is unable to fetch from a host
WebFetch는 페이지를 요청하기 전에 URL의 호스트 이름을api.anthropic.com으로 보내 Anthropic의 도메인 안전 차단 목록과 대조합니다. 이 메시지는 검사 결과 해당 호스트 이름을 가져올 수 없다는 응답을 받았다는 뜻입니다.
WebFetch 도메인 안전 검사 실패
URL을 가져오기 전에 WebFetch는 URL의 호스트 이름을api.anthropic.com으로 보내 Anthropic의 도메인 안전 차단 목록과 대조합니다. 검사를 완료할 수 없으면 WebFetch는 도메인이 안전한지 확인할 수 없으므로 페이지를 가져오지 않으며, 도구 결과에 대신 다음 메시지 중 하나가 표시됩니다.
rate-limited: 검사 엔드포인트가 HTTP429로 응답했습니다. 메시지는 Claude에게 해당 페이지 없이 계속 진행하고 나중에 최대 한 번만 다시 시도하라고 안내합니다. Claude Code는 실패한 검사를 캐시하지 않으므로, 이후 해당 도메인을 가져올 때 검사가 다시 실행됩니다. 네트워크의 세션에서 이 문제가 자주 발생한다면 설정에서skipWebFetchPreflight: true로 검사를 건너뛸 수 있습니다.Unable to verify: 검사 요청이 실패했거나, 시간 초과되었거나, 다른 오류 상태를 받았습니다. 네트워크에서api.anthropic.com을 차단한다면 해당 도메인을 허용 목록에 추가하거나, 설정에서skipWebFetchPreflight: true로 검사를 건너뜁니다.
The safety check for domain example.com is temporarily rate-limited (too many domain checks from this network). Retry after about a minute; retrying sooner will fail the same way.로 표시되었습니다.
v2.1.285 이전에는 속도 제한된 검사가 대신 Unable to verify 메시지로 보고되었습니다.
백그라운드 세션 오류
백그라운드 세션은 자체 대화형 터미널 없이 실행되므로, 터미널이 필요한 명령은 그곳에서 다르게 동작합니다. 이러한 메시지는 백그라운드 세션의 트랜스크립트, 세션에 연결된 터미널, 세션을 디스패치한 세션이나 셸에 나타나며, 아래의 워크트리 가드 항목의 경우에는 워크트리에 격리된 모든 세션 또는 워크트리 격리 서브에이전트를 실행 중인 세션에 나타납니다. 메시지가 특정 사용 환경에만 해당하는 경우 해당 항목에 명시되어 있습니다.백그라운드 세션에서 거부되는 명령
대화형 대화상자를 여는 명령은 백그라운드 세션에 터미널이 연결되어 있지 않은 동안에는 대화상자를 열 수 없습니다./install-github-app, /mcp 설정 목록, MCP 서버 메뉴의 인증 작업은 메시지로 응답합니다. /install-github-app과 /mcp 설정 목록의 경우, 세션이 에이전트 뷰의 Needs input 아래에도 표시되므로 세션을 찾아 연결한 후 명령을 다시 실행할 수 있습니다. 터미널이 연결되어 있는 동안에는 이러한 명령이 정상적으로 작동합니다.
v2.1.216 이전에는 /install-github-app 또는 /mcp 설정 목록이 거부된 후 세션이 Needs input 아래에 표시되지 않았습니다. v2.1.213부터 v2.1.215까지는 터미널이 연결된 동안 명령이 계속 작동했으며, 거부 메시지는 연결한 후 명령을 다시 실행하라고 안내했습니다. v2.1.208부터 v2.1.212까지는 터미널이 연결된 동안에도 Claude Code가 Can't open MCP settings in a background session과 같은 메시지와 함께 이러한 명령을 거부했습니다. 해당 버전에서는 일반 claude 세션에서 명령을 실행하거나 업그레이드하세요. v2.1.208 이전에는 이러한 명령이 백그라운드 세션 내에서 대화상자를 열었습니다. v2.1.208에서만 Claude Code가 백그라운드 세션에서 /model 선택기도 거부했으며, /upgrade는 브라우저를 여는 대신 업그레이드 URL을 출력했습니다.
문구에는 명령 이름이 포함됩니다. /mcp 설정 목록은 다음과 같이 보고합니다:
- 에이전트 뷰에서 세션에 연결하고 명령을 다시 실행하세요
- 또는
/mcp reconnect <server>,/mcp enable,/mcp disable처럼 메시지에 명시된 형식을 사용하세요. 이 형식은 연결하지 않고도 작동합니다
경로를 안전하게 해석할 수 없어 쓰기 또는 명령이 차단됨
Claude가 워크트리 격리 가드가 검증 가능한 하나의 위치로 해석할 수 없는 표기로 파일이나 작업 디렉터리를 지정했습니다. 가드는 대화형이든 백그라운드든 워크트리에 격리된 모든 세션과 워크트리 격리 서브에이전트에서 쓰기 작업과 명령 작업 디렉터리를 검사합니다. 가드는 작업이 공유 체크아웃에 도달하지 않는지 확인하기 전에 심볼릭 링크를 해석하며, 해석에 실패하면 작업이 그곳에 적용되도록 두지 않고 차단합니다. 메시지는 거부하는 경로 형식과 재시도 방법을 알려 줍니다:re-run the command from its direct symlink-free path로 끝납니다. v2.1.217 이전에는 가드가 심볼릭 링크를 해석하지 않고 경로 표기를 비교했기 때문에 이러한 표기가 차단되지 않았고, 심볼릭 링크를 거친 쓰기가 공유 체크아웃에 적용될 수 있었습니다.
해결 방법:
- 대개 아무것도 할 필요가 없습니다. 전체 메시지가 도구 오류로 Claude에 전달되고, Claude는 메시지에 명시된 직접 경로로 재시도합니다. 차단된 파일 편집의 경우 대화 뷰에는 짧은
Error editing file줄만 표시되며, 전체 메시지는Ctrl+O로 여는 트랜스크립트 뷰에 나타납니다. 차단된 명령은 명령 출력에 메시지를 출력합니다. - 같은 파일에서 차단이 반복되면 경로가
docs/current -> ../README.md처럼 대상에..이 포함된 커밋된 심볼릭 링크를 거칠 가능성이 높습니다. 링크를 거치지 말고 실제 경로로 대상 파일을 편집하도록 Claude에 요청하세요
경로가 네트워크 위치를 가리켜 쓰기 또는 명령이 차단됨
세션의 체크아웃이 로컬 디스크에 있는 상태에서, Claude가 사용자 컴퓨터에 없는 드라이브를 가리키는 경로, 즉\\server\share\file 같은 UNC 공유나 /net 자동 마운트 경로를 통해 파일이나 작업 디렉터리를 지정했습니다. 동일한 워크트리 격리 가드는 이러한 경로가 공유 체크아웃 밖에 머무는지 검증할 수 없으므로 작업을 차단합니다. 세션을 워크트리에 격리해도 차단은 해제되지 않습니다. 메시지는 대신 사용할 경로 형식을 알려 줍니다:
re-run the command from its local, plainly-spelled path로 끝납니다. v2.1.217 이전에는 가드가 경로 텍스트만 비교했기 때문에 UNC 또는 /net 경로를 통해 체크아웃 내부의 파일을 지정해도 차단되지 않았습니다.
해결 방법:
- 대개 아무것도 할 필요가 없습니다. Claude는 메시지가 요청하는 로컬 표기로 재시도합니다
워크트리 격리 검사에 의해 명령이 차단됨
Claude가 워크트리에 격리된 세션에서 Bash, PowerShell 또는 Monitor 명령을 실행했고, Claude Code가 다음 이유 중 하나로 이를 거부했습니다:- 명령이 메인 체크아웃이나 다른 워크트리에서 실행됩니다. 메시지에는 작업 디렉터리가
resolved to the shared checkout또는is in a different worktree라고 표시됩니다. - Bash 또는 Monitor 명령이 git을 메인 체크아웃으로 지정합니다.
- Claude Code가 Bash 또는 Monitor 명령의 텍스트만으로는 명령이 실행하는 git이 워크트리 내부에 머무는지 검증할 수 없습니다. git을 전혀 언급하지 않는 명령도 이 이유로 거부될 수 있습니다.
${!name}같은 변수 간접 참조를 확장하거나${ command; }같은 Bash 함수 치환을 실행하면 런타임에 생성되는 값 자체가 명령일 수 있기 때문입니다.
is isolated in the worktree <path>, but this command 다음에 Claude Code가 텍스트를 검증할 수 없었던 명령과 같은 이유가 표시됩니다:
- git이 메인 체크아웃을 가리키거나 명령 텍스트를 검증할 수 없는 경우: 아무것도 할 필요가 없습니다. Claude가 메시지를 읽고 마지막 문장이 요청하는 방식으로 명령을 다시 작성합니다. 사용자가 요청한 명령이 텍스트 내 확장 때문에 계속 거부된다면, 지적된 값을 리터럴로 작성하고 워크트리 내부에서 git을 별도의 일반 명령으로 실행하세요
- 의도적으로 메인 체크아웃에서 작업하려면 세션 밖의 터미널에서 직접 명령을 실행하세요
This session has no saved transcript
← 또는 /background로 백그라운드로 이동한 세션이 자체 턴을 실행하기 전에 중지되었고, 사용자가 이 세션에 연결했습니다. Claude Code가 세션을 이동해 온 원래 대화를 찾을 수 없으므로 세션에는 재개할 내용이 없습니다. 메시지는 이 세션에 대한 claude respawn 명령으로 끝납니다:
Press enter again to restart this session fresh가 표시되며, 행에서 Enter를 한 번 더 누르면 빈 대화로 세션이 다시 시작됩니다.
해결 방법:
- 중지된 세션을 새로 시작하려면 메시지의 ID로
claude respawn <id>를 실행하거나, 에이전트 뷰에서 해당 행에서Enter를 두 번 누르세요 - 세션이 응답을 완료했는데도 v2.1.214 이전 버전에서 이 거부가 표시된다면,
~/.claude/projects의 읽을 수 없는 폴더 때문에 트랜스크립트 검색에서 저장된 대화를 놓쳤을 수 있습니다. 검색 중 읽을 수 없는 폴더를 허용하는 v2.1.214 이상으로 업데이트하세요
This session is running in another terminal
에이전트 뷰에서 중지된 세션의 행을 열었는데, 저장된 대화가 이 컴퓨터의 다른 실행 중인 Claude Code 프로세스에서 이미 열려 있으므로, Claude Code는 같은 트랜스크립트에 쓰는 두 번째 프로세스의 시작을 거부합니다. 표시되는 메시지는 대화를 점유하고 있는 대상에 따라 다릅니다:running in another terminal: 백그라운드 세션이 아닌 프로세스가 대화를 점유하고 있습니다. 예를 들어claude -p실행이나,claude --resume또는/resume으로 대화를 재개한 터미널입니다. 행에는Open in a terminal도 표시됩니다.already open in another running Claude session: 다른 백그라운드 세션이 대화를 점유하고 있습니다.
running in another terminal의 경우: 해당 터미널에서 계속 작업하거나, 해당 프로세스를 종료하거나 완료될 때까지 기다린 후 다시 시도하세요already open in another running Claude session의 경우: 해당 세션을 사용하거나, 세션을 중지한 후 다시 시도하세요
already open in another running Claude session 거부만 존재했습니다. 터미널에서 재개한 대화는 열려 있는 것으로 간주되지 않았고, 행을 열면 같은 대화에 쓰는 두 번째 Claude Code 프로세스가 시작되었습니다.
This session’s saved conversation is no longer on disk
백그라운드 서비스가 꺼져 있는 동안 종료된 백그라운드 세션을 열었는데, 그 이후 트랜스크립트 정리가 저장된 대화를 제거했습니다. 예를 들어 컴퓨터가 몇 주 동안 꺼져 있었던 경우입니다. 이러한 행을 열면 일반적으로 저장된 대화가 재개됩니다. 재개할 내용이 남아 있지 않으면, Claude Code는 묻지 않고 세션의 원래 프롬프트를 다시 실행하는 대신 거부합니다:claude attach <id>는 이 텍스트를 출력합니다. 에이전트 뷰에서는 하단 문구가 더 짧으며 ctrl+x removes the row로 끝납니다.
해결 방법:
claude rm <id>를 실행하여 행을 삭제하세요. 유지되는 경우 중 하나에 해당하면claude rm은 대신 행과 워크트리를 유지하고 그 이유를 알려 줍니다- 세션의 원래 프롬프트를 새 대화로 다시 실행하려면
claude respawn <id>를 실행하세요
Worktree has commits that are not pushed anywhere
다른 곳에 저장되어 있는지 Claude Code가 확인할 수 없는 커밋을 워크트리에 보유한 백그라운드 세션을 삭제하려고 했습니다.claude rm이 진행 방법을 알려 줍니다:
The worktree has unpushed commits가 표시됩니다. 에이전트 뷰에서는 세션의 행에 같은 이유와 함께 not removed가 표시됩니다.
해결 방법:
- 커밋을 유지하려면 푸시하세요. 푸시로 커밋이
origin/claude/fix-login같은 원격 추적 브랜치에 올라가면 세션 삭제를 다시 시도하세요. - 메시지에서 커밋 폐기를 제안하는 경우, 먼저 워크트리, 커밋, 커밋되지 않은 변경 사항이 필요하지 않은지 확인하세요. 그런 다음 메시지가 안내하는 단계를 수행하세요. 에이전트 뷰에서 세션의 행에서
Ctrl+X를 두 번 누르거나,claude rm이 출력한claude rm <id> --discard-unpushed <commit>@<worktree-id>명령을 실행합니다. Claude Code가 다시 거부하면 새 메시지를 따르세요. - 메시지에 워크트리가 완료된 다른 세션에도 기록되어 있다고 표시되면, 다시 삭제해도 워크트리가 폐기되지 않습니다. 커밋을 푸시한 후 세션 삭제를 다시 시도하세요
claude rm이 커밋 요약을 kept 줄 자체에 표시했습니다. claude rm이 커밋을 요약할 수 없으면 kept 줄에 요약 대신 worktree has commits that are not pushed anywhere가 표시되었습니다.
v2.1.260 이전에는 메시지에 브랜치나 커밋이 명시되지 않았고 폐기 경로도 없었습니다. 이 경우에도 세션을 삭제할 수 있으며, 커밋되지 않은 변경 사항은 잃지만 브랜치와 커밋은 유지됩니다. 거부 메시지에 출력된 경로로 git worktree remove --force --force <path>를 실행한 다음 claude rm <id>를 실행하세요. 잠긴 워크트리의 경우 Git에는 --force가 두 번 필요합니다.
Terminal host process died
각 백그라운드 세션의 터미널은 백그라운드 서비스 아래의 호스트 프로세스에서 실행되는데, 서비스가 아직 연결을 유지하고 있는 동안 해당 프로세스가 종료되어 세션에 연결할 수 없었습니다. Linux와 WSL에서는 백그라운드 서비스가 몇 초마다 각 호스트 프로세스를 확인하고, 프로세스가 종료되었지만 서비스와의 연결이 닫히지 않은 경우 세션을 실패로 표시하며, 에이전트 뷰의 해당 행에 이유를 표시합니다:claude attach <id>는 호스트 종료로 이미 실패로 표시된 세션을 다시 시작하며, 그렇지 않은 경우 원인을 출력하고 종료합니다:
terminal host process died — its output is gone; the command was not run again이 표시되며, claude attach는 This command's terminal host process died — its output is gone and the command was not run again을 출력합니다. Claude Code는 명령을 사용자 대신 다시 실행하지 않습니다.
해결 방법:
- 에이전트 뷰에서 실패한 행에서
Enter를 누르세요. 세션이 새 호스트 프로세스에서 다시 시작되고 대화가 재개됩니다 - 셸에서
claude attach <id>를 다시 실행하세요. Claude Code가Session <id>'s terminal host died — restarting it on a fresh one…을 출력하고 세션을 다시 엽니다 - 셸 명령 행은 이 방법으로 다시 시작할 수 없습니다. 명령을 다시 실행하려면 다시 디스패치하세요
opening… · esc to cancel이 무기한 표시되었고 claude attach <id>는 오류를 보고하지 않고 계속 대기했습니다.
Session isn’t responding
백그라운드 세션을 열었고 백그라운드 서비스가 열기 요청을 수락했지만, 약 10초 동안 출력이 도착하지 않았습니다. 따라서 Claude Code는 세션의 터미널을 중계하는 프로세스가 출력을 전달할 수 없다고 판단하고, 대기하는 대신 시도를 종료합니다. 에이전트 뷰에서 Claude Code는 하단에 다시 시작 옵션을 제공합니다:claude attach <id>는 원인을 출력하고 종료합니다:
- 에이전트 뷰에서 같은 행에서
Enter를 다시 누르세요. Claude Code가 응답하지 않는 프로세스를 중지하고 세션을 다시 시작하며, 대화가 재개됩니다. 두 번째로 누르지 않으면 아무것도 중지되지 않습니다 - 셸에서
claude stop <id>를 실행한 다음claude attach <id>를 실행하세요 - 셸 명령 행의 경우 에이전트 뷰에서
Ctrl+X를 누르거나claude stop <id>를 실행하여 중지하세요. 명령을 다시 실행하려면 다시 디스패치하세요
Session was stopped while the respawn was in flight
프로세스가 실행 중이지 않은 백그라운드 세션을 열었고, Claude Code가 세션을 다시 시작하는 동안 다른 Claude Code 프로세스(예: 다른 터미널의claude stop)가 세션을 중지했습니다. Claude Code는 세션을 중지된 상태로 유지합니다:
- 세션을 직접 중지하지 않았다면, 에이전트 뷰에서 해당 행을 다시 열거나
claude respawn <id>를 실행하여 다시 시작하세요 - 직접 중지했다면 더 할 일은 없습니다. 세션은 중지된 상태로 유지됩니다
세션 에이전트를 더 이상 사용할 수 없음
--agent 또는 agent 설정으로 시작한 사용자 지정 에이전트를 실행하던 세션을 재개했는데, Claude Code가 해당 이름의 에이전트를 찾지 못했습니다. Claude Code는 해당 워크스페이스를 신뢰한 경우 세션의 원래 디렉터리를 먼저 검색한 다음, 재개하는 디렉터리를 검색합니다. 세션은 계속 재개되지만 기본 도구를 사용하므로 에이전트의 도구 제한이 더 이상 적용되지 않습니다:
/resume 또는 claude --resume을 실행하든, 비대화형 모드에서 재개하든 재개된 대화에 나타납니다. 비대화형 모드에서는 stderr에도 출력됩니다. --input-format stream-json을 사용하는 세션에서는 Agent SDK가 시작 후 에이전트를 제공하므로 경고가 표시되지 않습니다.
Claude Code는 폴백을 세션에 저장하지 않으므로, 조치를 취할 때까지 재개할 때마다 경고가 반복됩니다. 기본 제공 claude 에이전트는 기본 도구 세트로 폴백해도 달라지는 것이 없으므로 경고를 발생시키지 않습니다. v2.1.216 이전에는 Claude Code가 아무 알림 없이 기본 에이전트로 계속 진행했으며, 조회 범위가 재개하는 디렉터리뿐이었기 때문에 다른 디렉터리에서 재개하면 프로젝트 범위 에이전트가 사라졌습니다.
해결 방법:
- 세션의 프로젝트에 있는
.claude/agents/<name>.md에, 또는 개인 에이전트의 경우~/.claude/agents/<name>.md에 에이전트 파일을 다시 만든 후 다시 재개하세요 - 또는 실제로 존재하는 에이전트 이름을 지정하여
--agent <name>으로 재개하면, 세션이 대신 해당 에이전트로 실행됩니다 - 에이전트가 프로젝트 범위이고 세션의 원래 디렉터리를 신뢰하지 않았다면, 해당 디렉터리에서 Claude Code를 한 번 실행하고 신뢰 대화상자를 수락한 다음 다시 재개하세요
This session restarted after its next /loop wakeup was due
백그라운드 세션의 자체 페이스/loop가 중지되었습니다. 루프가 다음 깨우기를 기다리는 동안 세션의 프로세스가 종료되었고, 세션의 다음 프로세스가 시작되기 전에 해당 깨우기 시각이 지났습니다. 놓친 깨우기는 늦게 실행되지 않습니다. 알림에는 세션이 다시 시작되었을 때 깨우기가 얼마나 지연되었는지 표시됩니다:
- 루프를 계속하려면 세션에 회신하여
keep the loop running처럼 그렇게 말하세요. Claude가 회신과 함께 알림을 읽고 다음 깨우기를 예약할 수 있습니다 - 루프를 끝냈다면 아무것도 하지 않아도 됩니다. 루프는 이미 중지되었습니다
No LLM gateway: a gateway set in your shell isn’t passed to a session opened from another folder
이 메시지를 표시하는 백그라운드 세션은 LLM 게이트웨이를 사용하고 있지 않습니다. 게이트웨이 주소를 전달받지 못했으므로 요청이 실패합니다. 메시지는 Claude의 응답 대신 대화에 나타나며, 세션의 ID와 폴더가 채워져 있습니다:No LLM gateway: opened from another folder · respawn from ~/project가 표시됩니다.
ANTHROPIC_BASE_URL이 게이트웨이로 설정된 상태에서, 메시지에 명시된 폴더가 아닌 다른 폴더에서 세션을 디스패치하거나, 깨우거나, 다시 시작했습니다. 셸에서 내보낸 게이트웨이가 백그라운드 세션에 전달되는 경우는 LLM 게이트웨이를 참조하세요.
해결 방법:
- 설정에서 게이트웨이를 지정하는 프로젝트에서 에이전트 뷰를 사용한 경우:
ANTHROPIC_BASE_URL과 해당 API 키 또는 토큰을 설정 파일의env블록에 넣으세요.~/.claude/settings.json또는 세션 자체 프로젝트의.claude/settings.local.json을 사용하세요. 두 파일 모두 respawn된 세션이 읽습니다. 그런 다음 아무 폴더에서나 셸에서claude respawn <id>를 실행하세요. - 터미널에서 게이트웨이를 내보낸 경우: 게이트웨이 변수를 내보낸 터미널에서 메시지에 명시된 폴더로
cd한 다음 메시지의claude respawn <id>명령을 실행하세요. 세션이 저장된 대화에서 다시 시작됩니다.- 슈퍼바이저 자체가 같은 게이트웨이를 내보낸 셸에서 시작된 경우에만 게이트웨이가 세션에 전달됩니다. 그렇지 않은 경우, Dispatch fails with
Could not resolve authentication method에 설명된 대로 해당 터미널에서 슈퍼바이저를 다시 시작한 다음 respawn 명령을 다시 실행하세요.
- 슈퍼바이저 자체가 같은 게이트웨이를 내보낸 셸에서 시작된 경우에만 게이트웨이가 세션에 전달됩니다. 그렇지 않은 경우, Dispatch fails with
Not logged in · Please run /login 같은 로그인 오류가 표시되었습니다.
CLAUDE_CODE_PROCESS_WRAPPER 런처 오류
CLAUDE_CODE_PROCESS_WRAPPER가 설정되어 있지만 그 값을 사용할 수 없으므로, Claude Code는 런처 없이 실행하는 대신 해당 프로세스의 시작을 거부합니다. 구성 문제는 변수 이름으로 시작하고 이유를 설명하는 메시지로 보고됩니다. 예:
must exec, not daemonize라는 내용과 함께 런처가 출력한 내용이 표시됩니다. 런처 때문에 시작하지 못하거나 백그라운드 서비스에 연결하지 못한 세션은 Couldn't reach the background service (...) 안에 런처 문제를 이유로 보고합니다.
해결 방법:
- 변수를
exec "$@"를 호출하며 끝나는 실행 파일의 절대 경로로 설정하세요. 전체 계약은 런처 계약을 참조하세요 /status를 확인하세요. Self-exec 항목에 확인된 실행 명령이 표시되며, 실행 중인 백그라운드 서비스가 이와 일치하지 않으면 경고합니다. 또는 셸에서claude daemon status를 실행하세요- 설정의
env블록에서 값을 수정한 후claude daemon stop --any로 백그라운드 서비스를 다시 시작하여 다음 디스패치가 래핑된 서비스를 시작하도록 하세요
백그라운드 세션 시작 시 EUNKNOWN
Windows가 표준 이름이 없는 오류 코드로 프로그램 시작을 거부했으므로, 실패가EUNKNOWN으로 나타납니다. 일반적인 원인은 그룹 정책이나 AppLocker 같은 소프트웨어 제한 정책이 시작되는 프로그램을 차단하는 것입니다. 이 오류는 /background 또는 claude --bg로 백그라운드 세션을 시작할 때 나타납니다:
background service 대신 daemon이 표시됩니다.
npm 설치에서 npm install -g @anthropic-ai/claude-code가 바이너리를 교체하는 동안 나타나는 EUNKNOWN은 재설치 중 EACCES와 원인이 같으며, 설치가 끝난 후 재시도하면 해결됩니다.
Claude Code는 터미널을 닫아도 서비스가 유지되도록 PowerShell을 통해 백그라운드 서비스를 시작하며, PowerShell 7이 설치되어 있으면 이를 사용하고 그렇지 않으면 Windows PowerShell 5.1을 사용합니다. 두 PowerShell 모두 실행할 수 없으면 Claude Code는 대신 서비스를 직접 시작하므로, PowerShell만 차단하는 정책은 이 오류를 일으키지 않습니다.
v2.1.212 이전에는 Claude Code가 서비스를 시작할 때 Windows PowerShell 5.1만 사용했으므로, 그룹 정책이 PowerShell 5.1을 차단한 컴퓨터에서는 PowerShell 7이 설치되어 있어도 Couldn't start the session — EUNKNOWN: unknown error, uv_spawn으로 실패했습니다.
해결 방법:
- 메시지가
Couldn't start the session이면 v2.1.212 이상으로 업그레이드하세요. 이전 버전에서는 먼저 별도의 터미널에서claude daemon run을 실행한 다음 백그라운드 세션을 다시 시작할 수도 있습니다. 이 명령은 터미널의 포그라운드에서 백그라운드 서비스를 실행하므로, 서비스는 해당 터미널이 열려 있는 동안만 유지됩니다. - npm 설치가 바이너리를 교체하고 있었다면 완료될 때까지 기다린 후 백그라운드 세션을 다시 시작하세요
- npm 설치가 실행 중이지 않은데 v2.1.212 이상에서 오류가 나타나면, 제한 정책이 Claude Code 실행 파일을 차단하는지 Windows 관리자에게 확인하세요
- 터미널을 닫을 때 백그라운드 서비스가 중지된다면, Claude Code가 PowerShell 없이 서비스를 시작한 것입니다. 서비스가 터미널보다 오래 유지될 수 있도록 PowerShell 7을 설치하거나 관리자에게 PowerShell 차단 해제를 요청하세요.
백그라운드 세션 시작 시 EACCES
Claude Code가 백그라운드 세션을 호스팅하는 백그라운드 서비스를 시작하기 위해 자체 바이너리를 실행할 수 없었습니다. npm 설치에서 이는 대개 그 순간npm install -g @anthropic-ai/claude-code가 바이너리를 교체하고 있었음을 의미하며, 사용자가 실행했든 자동 업데이터가 실행했든 마찬가지입니다. 이 오류는 에이전트 뷰에서 세션을 열 때 나타납니다:
/background 또는 claude --bg로 세션을 시작하면 같은 이유가 Couldn't reach the background service (...) 안에 나타납니다. 같은 재설치 시간 동안 오류에 ENOENT, ENOEXEC 같은 다른 코드나 Windows에서는 EUNKNOWN 또는 EPERM이 표시될 수 있습니다. 재시도해도 계속되는 EUNKNOWN은 다른 원인에 의한 것입니다.
npm 설치에서 Claude Code는 재설치가 끝날 때까지 기다렸다가 자동으로 재시도합니다. 최대 10초 동안, 그리고 컴퓨터에서 Claude Code의 npm 설치가 여전히 실행 중인 것으로 확인되는 동안에는 최대 2분 동안 기다리며, 이는 다른 Claude Code 프로세스가 업데이트를 다운로드하는 경우를 포함합니다. 설치가 이 대기 시간보다 오래 걸리면, 실패 메시지에 단순 오류 코드 대신 업데이트가 명시됩니다:
- 몇 초 기다린 후 세션을 다시 열거나 다시 디스패치하세요. 메시지에 Claude Code가 업데이트 중이라고 표시되면 업데이트가 끝난 후 재시도하세요.
- npm 설치가 실행 중이지 않은데 오류가 계속되면, 사용자 계정으로 설치된 바이너리를 실행할 수 없는 것입니다. 바이너리와 해당 디렉터리의 권한을 확인하거나 Claude Code를 다시 설치하세요.
Background service exited before it became reachable
Claude Code가 백그라운드 서비스로 시작한 프로세스가 연결을 수락하기 전에 종료되어, Claude Code가 세션을 열 수 없었습니다. 서비스가 종료 전에 오류를 출력한 경우, 괄호 안의 이유에 종료 코드 또는 시그널과 서비스가 출력한 첫 번째 줄이 표시되며, 이 줄이 서비스를 중지시킨 원인을 알려 줍니다:Couldn't start the background service — 뒤에 표시됩니다. 서비스가 종료 전에 아무것도 출력하지 않은 경우 메시지에 대신 nothing on stderr가 표시됩니다.
Claude Code는 서비스의 오류 줄과 함께 실패를 보고합니다. v2.1.246 이전에는 45초 대기 후에야 서비스의 오류 줄 없이 background service did not become reachable within 45s로 실패가 나타났습니다.
인용된 이유 중 두 가지는 알려진 원인이 있습니다:
Error: claude native binary not installed.: 그 순간 npm 설치가 Claude Code 바이너리를 교체하고 있었으므로 서비스가 대신 npm의 플레이스홀더를 실행했습니다. 설치가 끝난 후 재시도하세요. 설치가 실행 중이지 않은데도 이 줄이 계속 나타나면 npm 설치를 완료하세요. v2.1.257 이전에는 macOS npm 자체 업데이트가 설치 시간 동안 매번 시작할 때마다 이 실패를 일으켰습니다.- Windows에서 매번 시작할 때마다 종료 코드 1과 함께
nothing on stderr:daemon.lock에 Claude Code가 시그널을 보낼 수도 없고 종료되었음을 증명할 수도 없는 프로세스가 기록되어 있어, 새 서비스가 매번 다른 서비스가 잠금을 보유하고 있다고 판단하고 종료합니다. 작성한 프로세스가 종료되었음을 Claude Code가 증명할 수 있는 잠금은 자동으로 교체되며 이 실패를 일으키지 않습니다. 매번 시작할 때마다 실패가 반복되면~/.claude/daemon.lock을 삭제한 다음 세션을 다시 열거나 다시 디스패치하세요. v2.1.257 이전에는 이러한 잠금이 파일을 삭제할 때까지 모든 시작을 차단했습니다.
- 메시지가 줄을 인용하면 해당 줄이 가리키는 문제를 해결한 다음 세션을 다시 열거나 다시 디스패치하세요. 다음 시도에서 서비스가 다시 시작됩니다
claude daemon status를 실행하여 현재 서비스가 실행 중인지 확인하세요
백그라운드 세션 시작 시 작업 디렉터리가 더 이상 존재하지 않음
백그라운드 세션을 시작한 디렉터리가 세션이 시작되는 동안 제거되었습니다. Claude Code는 세션을 시작하지 않으며, 메시지에 누락된 디렉터리가 표시됩니다:could not be resolved on disk를 보고합니다.
해결 방법:
- 메시지에 표시된 디렉터리를 다시 만들거나, 존재하는 디렉터리에서 디스패치한 다음 다시 시도하세요
This forked session could not be started
claude.ai에서 Remote Control 세션을 분기했는데, Claude Code가 사용자 컴퓨터에서 분기를 실행하는 백그라운드 세션의 시작을 완료하지 못했습니다. 이 알림은 분기된 세션의 트랜스크립트에 나타납니다:- 분기한 세션으로 돌아가 세션이 유휴 상태가 되면 다시 분기하세요
백그라운드 세션 디스패치 시 워크스페이스를 신뢰하지 않음
신뢰하지 않은 디렉터리에서 백그라운드 세션을 시작하거나 다시 시작했는데, 워크스페이스 신뢰 대화상자를 표시하여 확인을 요청할 수 없었습니다. Claude Code는 세션을 시작하지 않습니다:The home directory is trusted one session at a time: 세션의 디렉터리가 홈 디렉터리입니다. Claude Code는 홈 디렉터리에 대한 신뢰를 저장하지 않으므로, 이전 세션에서 그곳에서 대화상자를 수락한 것은 인정되지 않습니다.<path> could not be resolved on disk: Claude Code가 디스크에서 세션의 디렉터리를 찾을 수 없었습니다.
- 메시지에 표시된 디렉터리에서
claude를 실행하고 신뢰 대화상자를 수락한 다음 명령을 다시 실행하세요 - 홈 디렉터리 메시지의 경우 대화상자가 표시될 수 있도록 홈 디렉터리의 터미널에서 명령을 실행하거나, 대신 프로젝트 디렉터리에서 세션을 시작하세요
could not be resolved on disk메시지의 경우 디렉터리를 다시 만들거나, 존재하는 디렉터리에서 새 세션을 시작하세요
래퍼 및 IDE 오류
이러한 오류는 Claude Code 자체가 아니라 IDE 확장 프로그램이나 Agent SDK 애플리케이션과 같이 Claude Code를 실행한 프로그램에서 발생합니다.Subprocess initialization did not complete within 60000ms
이 오류는 VS Code 확장 프로그램이나 Agent SDK 애플리케이션이 실행한 Claude Code 프로세스가 준비되었다고 제때 보고하지 않았음을 의미합니다. 그러면 확장 프로그램이나 애플리케이션이 해당 프로세스를 중지합니다. VS Code 대화에서 이 오류는Claude Code did not finish starting으로 시작합니다. 예:
Subprocess initialization did not complete within과 시간 제한으로 시작한 다음 Claude Code가 보고한 내용이 이어집니다. 예:
- VS Code에서 다시 시도하려면 메시지를 보냅니다. 로그인하는 동안 오류가 나타났다면 대신 로그인 방법을 다시 선택합니다.
- Claude Code가 어디까지 진행했는지 확인하려면 대화의 오류 아래에 있는 View output logs를 클릭하거나 Command Palette에서 Claude Code: Show Logs를 실행합니다. 문제를 보고할 때는
Subprocess initialization줄 주변의 항목을 포함합니다. - 네트워크를 확인하려면 네트워크 구성을 참조합니다. 메시지에서 로그인이나 인증을 확인하라고 하면 로그인 및 인증을 참조합니다.
- 메시지에서 SessionStart 또는 Setup 훅이 아직 끝나지 않았다고 하면 훅이 얼마나 오래 실행되는지 확인합니다. VS Code에서는 Claude Code가 이러한 훅이 실행 중이라고 보고하는 처음 10분은 60초 제한에 포함되지 않습니다. 느린 훅이 더 빨리 끝나도록 하거나, 비동기가 아닌 훅의
timeout을 낮추거나, 훅을 제거합니다. - Agent SDK 애플리케이션이
startup()을 호출한다면, 전체 시작 과정에 충분하도록initializeTimeoutMs를 길게 설정하거나, 설정하지 않은 채로 두어 보고된 훅 시간이 최대 10분까지 포함되지 않도록 합니다.
Subprocess initialization did not complete within 60000ms — check authentication and network connectivity가 포함되었습니다. 이 문구가 표시되면 확장 프로그램이나 SDK를 업데이트하세요.
Claude Code process exited with code N
기본claude 프로세스가 0이 아닌 코드로 종료되었습니다. 종료 코드만으로는 무엇이 실패했는지 알 수 없습니다. 실제 오류는 프로세스 자체의 출력에 있으며, 래퍼가 캡처한 경우 이를 추가하고 그렇지 않으면 로그에 유지합니다.
4294967295로 종료될 수 있습니다. 해당 종료가 턴 경계에서 발생하고 대기 중인 메시지가 없으며 백그라운드 작업이 실행 중이 아닐 때 VS Code 확장 프로그램은 이 오류를 표시하지 않고 세션을 조용히 닫습니다. 다음 메시지는 대화를 재개합니다.
v2.1.273 이전에는 확장 프로그램이 아무것도 손실되지 않았음에도 불구하고 모든 턴 경계에서 해당 종료에 대한 오류를 표시했습니다.
수행할 작업:
- VS Code에서 오류와 함께 표시되는 View output logs 링크를 따라 기본 오류를 확인합니다.
- Agent SDK 애플리케이션에서 메시지 루프 주변의 오류를 캡처합니다. CLI 프로세스 종료 아래의 항목은 각 SDK 언어에서 코드가 수신하는 내용을 다룹니다.
- 터미널에서 동일한 프로젝트에서
claude를 실행합니다. 오류는 일반적으로 실제 오류 메시지와 함께 재현되며, 이를 이 페이지에서 조회할 수 있습니다. - 터미널에서
claude doctor를 실행하여 설치 및 구성을 확인합니다.
Could not locate the Claude CLI on PATH
VS Code 확장 프로그램은 Windows에서 통합 터미널에서 Claude Code를 열 때, 터미널의 셸이 PowerShell이고 확장 프로그램이 PATH에서 설치된claude 실행 파일을 찾을 수 없을 때 이 오류를 표시합니다. 확장 프로그램은 PATH에서 설치된 claude를 찾을 때까지 Claude Code 실행을 거부합니다.
- VS Code 외부에서 새 PowerShell 창을 열고
where.exe claude를 실행합니다. 경로를 출력하지 않으면 CLI가 PATH에 없습니다. PATH 확인을 따라 설치 디렉터리를 추가합니다. 경로를 출력하면 항목은 PowerShell 프로필에서 오거나 VS Code가 아직 반영하지 않은 PATH 변경에서 옵니다. 다음 두 단계는 이러한 경우를 다룹니다. - PowerShell 프로필이 아닌 사용자 또는 시스템 환경 변수로 PATH 항목을 설정합니다. 확장 프로그램은 프로필을 실행하지 않으므로 거기에만 있는 PATH 편집은 절대 도달하지 않습니다.
- PATH를 변경한 후 VS Code를 다시 시작합니다. 확장 프로그램은 VS Code가 시작할 때 캡처한 PATH를 확인하므로 PATH 변경은 다시 시작한 후에만 적용됩니다.
The Claude Code program for this computer could not be found
VS Code 확장 프로그램이 내부에 번들된 Claude Code 사본을 찾았지만 현재 컴퓨터용으로 빌드된 사본이 없습니다. 메시지에는 컴퓨터에 필요한 빌드가 표시됩니다.- 메시지에 확장 프로그램이 포함하고 있는 빌드가 명시되어 있으면 다른 플랫폼용 확장 프로그램 패키지를 설치한 것입니다. 메시지에 표시된 빌드용으로 만들어진 패키지를 설치합니다.
- 메시지에 확장 프로그램이 포함하고 있는 빌드가 명시되어 있지 않으면 편집기의 Extensions 뷰에서 Claude Code 확장 프로그램을 다시 설치합니다.
- 또는 두 경우 모두
claudeCode.claudeProcessWrapper를 별도로 설치한claude바이너리로 설정합니다.
Unsupported platform: <platform>-<arch>. No compatible Claude Code binary found.로 표시되었습니다.
The connection to Claude Code ended before this message completed
VS Code 확장 프로그램이 메시지를claude 프로세스로 보냈고, 프로세스가 이를 인정하거나 완료하기 전에 오류 없이 연결이 종료되었습니다. 확장 프로그램은 메시지가 처리되었는지 여부를 알 수 없으므로 다시 보내도록 요청합니다.
- 메시지를 다시 보냅니다. 다음 메시지는 대화를 재개하는 새로운
claude프로세스를 시작합니다. - 반복되면 동일한 프로젝트의 터미널에서
claude를 실행합니다. 프로세스를 계속 종료하는 오류는 일반적으로 실제 오류 메시지와 함께 재현됩니다.
되돌리기 경고 및 오류
이 메시지들은/rewind 코드 복원에서 나옵니다. Restored the code, but skipped N files는 Claude Code가 일부 경로를 건너뛰었다는 경고입니다. No files were restored는 아무것도 복원하지 못했다는 의미의 오류입니다.
코드는 복원되었지만 파일을 건너뜀
/rewind 코드 복원이 추적된 경로 중 하나 이상을 작성하거나 삭제하지 않고 건너뛰었습니다. Claude Code는 다음과 같은 경우에 경로를 건너뜁니다:
- 심볼릭 링크, 하드 링크 또는 기타 일반 파일이 아닌 경우
- 체크포인트 이후 디렉토리가 변경된 경우
- 백업을 안전하게 읽을 수 없는 경우
/rewind가 추적된 경로의 링크를 통해 작성하고 삭제했으며, 부분 복원을 보고하지 않았습니다.
- 건너뛴 파일을 식별하여 아래 단계로 각각을 처리할 수 있도록 합니다. 메시지는 개수만 제공하므로, 복원이 실행될 때 건너뛴 각 경로를 이름으로 나열하는 디버그 로그
~/.claude/debug/<session-id>.txt를 확인하고, 다음 복원 전에/debug로 디버그 로깅을 켭니다. macOS 또는 Linux에서는 대신 링크를 직접 찾을 수 있습니다: 심볼릭 링크는find . -type l, 하드 링크된 파일은find . -type f -links +1을 사용합니다. - 건너뛴 파일이 dotfile 관리자가 관리하는 설정 파일이나 pnpm과 같은 도구로 하드 링크된 파일처럼 의도적으로 만든 링크인 경우, 되돌리기는 해당 내용을 그대로 두었습니다. 세션의 변경 사항을 취소하려면 Claude에게 편집을 되돌리도록 요청하거나 파일을 직접 편집합니다.
- 링크를 만들지 않았다면, 해당 경로의 내용을 신뢰하기 전에 검사합니다.
파일이 복원되지 않음
Claude Code는/rewind로 코드를 복원할 때 해당 체크포인트의 파일 중 어느 것도 복원할 수 없으면 이 메시지를 표시합니다. 각 파일에 대해 Claude Code가 편집하기 전에 저장한 백업이 누락되었거나, Claude Code가 파일을 작성하거나 삭제할 수 없습니다.
/rewind는 여전히 체크포인트를 나열하지만, 그 중 하나로 되돌리면 이 오류로 실패할 수 있습니다. 메시지에 N paths were skipped for link safety도 표시되면, 해당 경로에 대해 코드는 복원되었지만 파일을 건너뜀을 참조합니다.
세션을 포크할 때, 예를 들어 --fork-session 또는 /branch를 사용하면, Claude Code는 원본 세션의 백업을 포크로 복사합니다. Claude Code가 백업을 복사할 수 없을 때, 예를 들어 디스크가 가득 찼을 때, 해당 백업은 포크에서 누락됩니다. 이를 필요로 하는 체크포인트로 되돌리면 이 오류로 실패할 수 있습니다.
해야 할 일:
- 다른 방법으로 변경 사항을 취소합니다: Claude에게 편집을 되돌리도록 요청하거나, 버전 제어에서 파일을 복원합니다. 백업이 없으면
/rewind를 다시 실행해도 같은 방식으로 실패합니다. - Claude Code가 파일을 작성하거나 삭제할 수 없으면, 파일 권한과 같이 작성을 차단하는 것을 수정한 후
/rewind를 다시 실행합니다. - 향후 세션에서 백업을 더 오래 유지하려면
cleanupPeriodDays를 높입니다.
세션 저장 경고
Claude Code는 세션 트랜스크립트를 저장하지 않을 때 입력 상자 아래의 지속적인 줄에 이러한 경고를 표시합니다. 세션은 어느 쪽이든 계속 작동합니다. 경고는 나중에--resume에서 세션이 누락될 수 있음을 알려줍니다.
트랜스크립트 쓰기가 실패하고 있습니다
Claude Code는 작업할 때 트랜스크립트를 디스크에 저장하며, 트랜스크립트 파일에 대한 쓰기가 실패하고 있습니다. 메시지는 원인을 기본 오류 코드와 함께 이름 지정합니다. 예를 들어 디스크가 가득 찬 경우:- 자체적으로 해결되지 않는 조건의 첫 번째 실패: 디스크 가득 참, 디스크 할당량 초과, 읽기 전용 파일 시스템, 파일 시스템의 길이 제한을 초과하는 경로, 또는 macOS 및 Linux에서 권한 오류
- 최소 1분에 걸친 반복 실패(다른 모든 경우 포함): Windows의 권한 오류(바이러스 백신 스캔이 단일 쓰기를 실패하게 한 후 재시도 시 성공할 수 있음)
--resume에서 최근 메시지가 누락된 것이 첫 번째 신호였습니다.
할 일:
- 오류 코드가 이름 지정하는 조건을 수정합니다:
ENOSPC의 경우 디스크 공간 확보;EDQUOT의 경우 할당량 올리기 또는 지우기;EACCES,EPERM또는EROFS의 경우 트랜스크립트 위치에 대한 쓰기 액세스 복구 - 경고는 다음 성공적인 쓰기에서 자동으로 지워집니다. 재시작이 필요하지 않습니다.
- 경고가 표시되는 동안 전송된 메시지는 나중에 세션을 재개할 때 여전히 누락될 수 있습니다.
CLAUDE_CODE_SKIP_PROMPT_HISTORY가 설정되어 있어서 트랜스크립트 저장이 꺼져 있습니다
이 세션은CLAUDE_CODE_SKIP_PROMPT_HISTORY가 설정된 상태로 시작되었으므로 Claude Code는 이에 대한 트랜스크립트나 프롬프트 기록을 작성하지 않습니다:
- 의도적으로 변수를 설정한 경우 조치가 필요하지 않습니다. 공지는 세션이
--resume,--continue또는 위쪽 화살표 기록에 나타나지 않음을 확인합니다. - 그렇지 않은 경우
claude를 시작하는 셸 또는 스크립트에서 변수를 제거한 다음 새 세션을 시작합니다. 현재 세션의 메시지는 소급하여 저장되지 않습니다.
상속된 CLAUDE_CODE_CHILD_SESSION 마커로 인해 트랜스크립트 저장이 꺼져 있습니다
Claude Code는 생성하는 서브프로세스에서CLAUDE_CODE_CHILD_SESSION을 설정하고, 이를 상속하는 대화형 세션을 중첩된 것으로 취급합니다: Claude Code는 이에 대한 트랜스크립트를 저장하지 않으므로 Claude 자체가 시작하는 세션이 --resume 목록을 채우지 않습니다. 이 공지는 현재 세션이 마커를 상속했음을 의미합니다:
claude를 실행했을 때 예상되며, 마커가 오래 지속되는 중간 매개체(예: 터미널, screen 세션 또는 Claude Code 세션이 원래 시작한 런처)를 통해 누출되었을 때 오분류를 신호합니다.
tmux 내에서 Claude Code는 tmux 서버의 전역 환경을 통해 도착한 마커를 감지하고 저장을 계속하므로 이 경우 이 공지가 나타나지 않습니다.
할 일:
- 의도적으로 다른 Claude Code 세션 내부에서 이 세션을 시작한 경우 조치가 필요하지 않습니다.
- 이것이 최상위 세션인 경우
CLAUDE_CODE_FORCE_SESSION_PERSISTENCE=1을 설정하여 종료하고 재시작합니다. 저장은 재시작부터 적용되므로 이전에 전송된 메시지는 저장되지 않습니다. - 동일한 터미널 또는 런처에서 향후 시작을 수정하려면 해당 환경에서
CLAUDE_CODE_CHILD_SESSION을 제거합니다.
구성 경고
대화형 세션에서 Claude Code가 시작 시 표시한 경고를 찾으려면 먼저 시작 배너 아래를 확인한 다음 디버그 로그를 확인하세요:- 시작 배너 아래의 행:
⚠ Deny rule Bsh matches no tool · check for typos처럼 권한 규칙에 관한 일부 경고 - 디버그 로그: Claude Code는 디버그 모드에서만 이 로그를 유지합니다. 로그의 경고를 읽으려면 셸에서
claude --debug-file <path>로 Claude Code를 시작한 다음 해당 경로의 파일을 여세요.
Claude Code가 복구 불가능한 인터페이스 오류 후 종료됨
Claude Code는 터미널 인터페이스가 복구할 수 없는 오류에 부딪혀 종료될 때 이 메시지를 출력하며, 이는 두 렌더러 모두에서 발생할 수 있습니다. 두 번째 문장은 전체 화면 렌더러가 시작되는 동안 오류가 발생했을 때만 나타납니다:- Claude Code를 다시 시작하세요. 대화를 이어서 진행하려면 같은 디렉터리에서
claude --resume을 실행하세요. - 메시지가 전체 화면 렌더러를 언급하면 전체 화면 렌더링에서 전체 화면을 켠 방식에 따라 다음 실행이 어떻게 동작하는지, 그리고 전체 화면을 다시 시도하거나 클래식 렌더러를 유지하는 방법을 확인하세요.
에이전트 설명이 15.0k 토큰 제한을 초과함
Claude Code는 stderr가 아닌 대화 보기의 시작 알림으로 이 경고를 표시합니다. 기본 제공 에이전트를 제외한 서브에이전트의 설명을 합친 양이 Claude Code의 추정으로 15,000 토큰을 초과합니다. 각 에이전트는 이름과description frontmatter가 계산에 포함됩니다. Claude Code는 합계가 제한을 초과하는지 여부와 관계없이 모든 에이전트를 로드하므로 이 경고는 로드되는 내용을 변경하지 않습니다.
- 에이전트 파일의
descriptionfrontmatter를 줄이거나 Claude에게 정리하도록 요청하세요. - 더 이상 사용하지 않는 에이전트 파일을 제거하세요.
훅에서 공백이 포함된 경로에 따옴표가 필요함
대화 보기의 이 알림은 훅의 스크립트 경로에 공백이 있는데 따옴표로 묶이지 않아 스크립트가 실행되지 않았다는 의미입니다. 해당 훅은 셸 형식의asyncRewake 훅입니다. 훅의 command에서 python3 같은 인터프리터 뒤에 따옴표로 묶이지 않은 경로 자리 표시자가 오며, 해석된 경로에 공백이 포함되어 있습니다.
알림은 훅의 이벤트 이름으로 시작하며 스크립트를 명시합니다:
- 알림이 명시한 스크립트를 실행하는 훅의
command에서 경로를 큰따옴표로 묶으세요. JSON 파일에서는"command": "python3 \"${CLAUDE_PLUGIN_ROOT}/hooks/check.py\""처럼 작성합니다.
지침 파일이 로드되지 않음
대화형 세션의 대화 보기에 나타나는 이 알림은 존재하는 메모리 파일이 로드되지 않았다는 의미입니다. 읽기 제한이 적용되어 있습니다.a Read deny rule covers it:Read거부 규칙이 작성된 그대로의 파일 경로 또는 해당 파일의 링크가 가리키는 위치와 일치합니다it's read from outside your working directories, where reads are blocked:permissions.blockReadsOutsideWorkingDirectories가 켜져 있는 동안 파일이 작업 디렉터리 외부로 해석됩니다where it leads couldn't be worked out: 예를 들어 파일이 직접 또는 다른 링크를 통해 자기 자신을 다시 가리키는 링크인 경우입니다
and 3 more instruction files not loaded처럼 나머지 개수가 표시됩니다.
할 일:
- 제한이 의도된 것이라면 아무것도 하지 않아도 됩니다. 세션은 해당 파일의 지침 없이 실행됩니다.
a Read deny rule covers it때문에 보류된 파일을 로드하려면 해당 규칙을 제거하거나 범위를 좁히세요. 그런 다음 새 세션을 시작하세요.it's read from outside your working directories, where reads are blocked때문에 보류된 파일을 로드하려면 파일 또는 링크 대상을 작업 디렉터리 안으로 옮기세요. 그런 다음 새 세션을 시작하세요.where it leads couldn't be worked out때문에 보류된 파일을 로드하려면 파일이 자기 자신을 다시 가리키는 링크인지 확인하세요. 그렇다면 링크가 존재하는 파일을 가리키도록 하거나 그 자리에 일반 파일을 두세요. 그런 다음 새 세션을 시작하세요.
스킬, 명령 또는 워크플로가 로드되지 않았습니다(이름이 예약됨)
스킬 폴더, frontmattername, .claude/commands/의 파일 또는 하위 폴더, 또는 저장된 워크플로가 anthropic-skills 이름을 사용하거나 anthropic-skills:로 시작하는 이름을 사용합니다. Claude Code는 claude.ai에서 동기화된 스킬을 위해 해당 이름을 예약하며 해당 항목을 로드하지 않습니다.
Claude Code는 stderr가 아닌 대화 보기의 시작 알림으로 이 경고를 표시합니다:
name: 줄, 또는 이름을 바꿀 워크플로. 둘 이상의 항목이 거부되면 알림은 · 2 more 같은 개수로 끝나며 디버그 로그에 각 항목이 명시됩니다.
할 일:
- 알림이 명시한 항목의 이름을 바꾸거나 알림이 가리키는
name:줄을 편집한 후 세션을 다시 시작하세요.
스킬 또는 명령 이름이 거부됨
이 시작 알림은 Claude Code가 하나 이상의 스킬 또는 사용자 지정 명령의 이름을 거부했다는 의미이며, 해당 항목은 로드되지 않았거나name 필드 없이 로드되었습니다:
- 로드되지 않음: Claude Code가 디렉터리 이름이나 명령 파일의 이름 또는 하위 폴더처럼 스킬 또는 명령이 사용하는 이름을 거부했습니다. 해당 항목은
/메뉴에 없으며 Claude가 호출할 수 없습니다. 디버그 로그의 해당 줄은<name> is not offered로 표시됩니다. name필드 무시됨: Claude Code가 스킬의 frontmattername을 거부했습니다. 스킬은 여전히 로드되지만/메뉴에name값이 표시되지 않으며, 해당 값을 입력해도 스킬이 호출되지 않습니다. 디버그 로그의 해당 줄은<name value> is not shown for <skill>로 표시됩니다.
- 셸에서
claude --debug로 Claude Code를 시작하고 디버그 로그에서[names]를 검색하세요. 알림이 집계한 각 이름마다 한 줄이 있습니다. 해당 줄은 폭이 없는 공백을\u{200B}로 표기하는 것처럼 일부 숨겨진 문자를 코드로 표기하므로 문자의 위치를 확인할 수 있습니다. - 폴더나 파일의 이름을 바꾸거나
name:줄을 편집하여 스킬 이름에 포함할 수 없는 문자를 제거하거나, 256자를 초과하는 이름을 줄이세요. 그런 다음 파일이 Claude Code가 변경 사항을 감시하는 디렉터리에 있는 경우가 아니라면 세션을 다시 시작하세요. 직접 작성하지 않은 플러그인의 스킬이라면 플러그인 작성자에게 이름 변경을 요청하세요.
워크스페이스가 신뢰되지 않음
Claude Code는 프로젝트의.claude/settings.json 또는 .claude/settings.local.json에서 permissions.allow 규칙 또는 permissions.additionalDirectories 항목을 찾았지만 프로젝트 설정의 허용 규칙에는 워크스페이스 신뢰가 필요하기 때문에 적용하지 않았습니다. 메시지에 표시되는 개수, 설정 이름, 파일은 구성에 따라 다릅니다. deny 및 ask 규칙은 영향을 받지 않습니다.
- 해당 디렉터리에서
claude를 실행하고 신뢰 대화 상자를 수락하세요. 프로젝트 허용 규칙 및 워크스페이스 신뢰에서 해당 수락이 어느 폴더에 적용되는지 설명합니다. -p를 사용하는 비대화형 모드에서는 대화 상자가 표시되지 않습니다. 메시지가 출력하는 정확한projects키를 사용하여~/.claude.json에hasTrustDialogAccepted항목을 설정하세요.- 메시지가
.claude/settings.local.json을 명시하고 git 저장소 외부 또는 홈 디렉터리에서 Claude Code를 시작했다면 v2.1.200 이상으로 업데이트하세요. 버전 2.1.196부터 2.1.199까지는 이러한 워크스페이스에서 사용자 자신의.claude/settings.local.json을 저장소에서 제공된 것으로 취급했습니다. v2.1.207 이상에서는 폴더를 신뢰하지 않은 경우 git 저장소 외부에서 업데이트만으로는 충분하지 않습니다. 폴더가 저장소 내부에 있지 않음을 확인하려면 git을 실행해야 하며, Claude Code는 신뢰 대화 상자를 수락한 후에만 이 검사를 실행하므로 첫 번째 단계를 사용하세요. 홈 디렉터리와 기타 구성 홈은 예외이며 대화 상자를 기다리지 않습니다. 프로젝트 허용 규칙 및 워크스페이스 신뢰를 참조하세요.
작업 디렉터리가 네트워크 경로임
Claude Code는 네트워크 경로를 작업 디렉터리로 추가하지 않습니다. 네트워크 경로를 조회하면 경로에 지정된 호스트에 연결할 수 있으며, Windows에서는 이 연결로 호스트에 자격 증명이 전송될 수 있습니다. 따라서 Claude Code는 조회하지 않고 경로를 거부합니다. 네트워크 경로로/add-dir을 실행하면 다음 메시지가 표시됩니다:
--add-dir 또는 permissions.additionalDirectories로 네트워크 경로를 전달하면 Claude Code는 해당 디렉터리 없이 시작합니다. 대화형 세션에서는 메시지가 다른 시작 경고와 함께 디버그 로그에 기록되므로 시작 시 메시지가 표시되지 않습니다.
Claude Code가 이 방식으로 거부하는 경로는 다음과 같습니다:
\\server\share같은 UNC 공유/net/<host>같은 자동 마운트 경로(해당 호스트의 자동 마운트 아래 디렉터리에서 Claude Code를 실행한 경우 제외). 해당 자동 마운트 아래의 읽기는 여전히 네트워크 경로 검사를 거칩니다.- 심볼릭 링크 또는 정션을 통해 네트워크 위치에 도달하는 로컬 경로
\\wsl$ 경로는 네트워크 경로로 간주되지 않습니다.
할 일:
- Windows에서는 공유를 드라이브 문자에 매핑하고 실행 시 해당 드라이브를 전달하세요. 예를 들어 PowerShell에서
net use Z: \\server\share를 실행한 다음claude --add-dir Z:\를 실행합니다. - macOS 또는 Linux에서는 공유를 로컬 경로에 마운트하고 대신 해당 경로를 추가하세요.
- 경로가
permissions.additionalDirectories에 있으면 해당 경로를 나열한 설정 파일에서 제거하세요.
원격 관리형 설정을 로드하지 못함
세션이 서버 관리형 설정 적용 대상이지만 Claude Code가 설정을 가져오지 못했거나 서버가 반환한 내용을 적용하지 못했으므로 대화형 세션과 Claude Desktop의 Code 탭에서 이 경고를 표시합니다. 괄호 안의 원인은network error, request timed out, authentication rejected (401)처럼 무엇이 실패했는지를 나타냅니다. no setting in the server response could be applied as written 원인은 서버가 응답했지만 반환된 설정 중 검증을 통과한 것이 없음을 의미합니다. v2.1.282 이전에는 이 원인이 server returned invalid settings로 표시되었습니다.
줄의 나머지 부분은 세션이 어떤 정책으로 실행되는지를 나타냅니다:
- 이전에 성공한 가져오기에서 캐시된 설정: Claude Code는 보류된 환경 변수를 제외한 캐시된 정책으로 세션을 실행하며, 줄에
using cached policy가 표시됩니다. - 적용할 캐시된 설정이 없음: Claude Code는 서버 관리형 설정 없이 세션을 실행하며, 줄에
no remote policy applied가 표시됩니다. 예를 들어 컴퓨터가 아직 설정을 가져온 적이 없거나 마지막으로 가져온 지 24시간이 넘은 경우입니다.
Remote managed settings are still loading: 세션이 진행될 때 가져오기가 아직 실행 중이었습니다Remote managed settings did not load: 가져오기가 응답 없이 끝났습니다Remote managed settings have now loaded: 이러한 경고 중 하나가 표시된 후 설정이 로드되었으며, 줄의 나머지 부분은 원격 정책이 적용되는지를 나타냅니다
- 메시지가 명시한 원인에 따라 조치하세요: 네트워크 원인의 경우 이 머신이
api.anthropic.com에 도달할 수 있는지 확인하고, 인증 원인의 경우/status로 로그인 상태를 확인하세요. no setting in the server response could be applied as written의 경우 관리자에게 서버의 설정을 수정하도록 요청하세요.- 전체 진단을 보려면
/status또는claude doctor를 실행하세요.
Claude Code가 조직의 설정을 로드하지 못함
서버 관리형 설정을 포함한 조직의 설정이 먼저 로드되어야 하는데 Claude Code가 이를 로드하지 못했으므로 세션이 시작되지 않았습니다. 예를 들면 다음과 같습니다:Claude Code can't start this session yet 제목의 대화 상자에 표시되면, 설정이 로드되는 즉시 대화 상자가 닫히고 세션이 시작됩니다.
비대화형 모드와 백그라운드 세션에서는 Claude Code가 대신 메시지를 출력하고 상태 1로 종료합니다.
할 일:
could not connect, 또는the reply came from a network proxy, not Anthropic: 네트워크 연결을 확인하고, 회사 네트워크에서는 IT 부서에api.anthropic.com/api/claude_code/policy_limits및api.anthropic.com/api/claude_code/settings로의 HTTPS를 허용하도록 요청하세요. 그런 다음 Retry now를 선택하거나 명령을 다시 실행하세요.timed out,Anthropic returned an error, 또는Anthropic asked it to retry shortly: 대화 상자가 재시도하도록 두거나 나중에 명령을 다시 실행하세요. 계속 발생하면 status.anthropic.com을 확인하세요.still loading, 또는couldn't verify your sign-in with Anthropic yet: 대화 상자가 재시도하도록 두거나 명령을 다시 실행하세요. 로그인 메시지가 계속 다시 나타나면 셸에서claude auth login을 실행하여 다시 로그인하세요.Your Claude session has expired: 이 머신에 저장된 로그인이 더 이상 유효하지 않으므로 재시도해도 도움이 되지 않습니다. 대화 상자에서 Sign in again을 선택하여 Claude Code를 닫은 다음, 셸에서claude auth login을 실행하세요. 이 명령은 세션을 시작할 수 없는 동안에도 작동합니다.none of the settings the server returned could be applied as written: 관리자에게 조직의 서버 관리형 설정을 수정하도록 요청한 다음 재시도하세요.
관리형 설정이 승인되지 않음
조직의 서버 관리형 설정에 승인이 필요한 설정이 포함되어 있는데 보안 승인 대화 상자를 거부했으므로, Claude Code는 설정을 적용하지 않고 종료합니다:- Claude Code를 다시 시작하고 대화 상자를 승인하여 조직의 설정으로 계속 진행하세요. 거부한 대화 상자는 기억되지 않으므로 다음 시작 시 다시 나타납니다.
- 대화 상자에 나열된 설정이 확실하지 않으면 승인하기 전에 조직의 관리형 설정을 유지 관리하는 담당자에게 문의하세요.
관리형 설정에 승인이 필요함
조직의 서버 관리형 설정에 보안 승인 대화 상자에서 승인이 필요한 설정이 포함되어 있습니다. 실행한claude plugin 명령은 키보드에서 입력을 읽을 수 없었으므로 해당 대화 상자를 표시할 수 없었습니다. 이는 명령의 입력을 파이프하거나 리디렉션하고, macOS와 Linux에서는 /dev/tty도 열 수 없을 때 발생합니다. 명령은 아무것도 변경하기 전에 중지되었습니다:
- 터미널에서
claude를 실행하고 대화 상자가 나타나면 설정을 승인한 다음, 같은claude plugin명령을 다시 실행하세요. Claude Code는 승인과 승인된 설정을 구성 디렉터리에 보관합니다. 중지된 명령이 다른 사용자로 실행되었거나CLAUDE_CONFIG_DIR이 설정된 상태로 실행되었다면, 두 명령이 같은 디렉터리를 사용하도록claude도 같은 방식으로 실행하세요.
관리형 설정이 기본 모델을 차단함
조직의 관리형 설정이 Default 옵션이 가리키는 모델과 단계적으로 낮출 수 있는 모든 모델을 차단합니다. Default 옵션으로 시작하려던 세션은 차단된 모델을 실행하는 대신 시작 시 종료됩니다. 표시되는 메시지는 차단하는 설정에 따라 다릅니다.deniedModels 목록이 차단하는 경우 메시지는 다음과 같습니다:
availableModelsMatch가 "exact"로 설정된 availableModels 목록에서 해당 모델이 빠진 경우 메시지는 다음과 같습니다:
- 설정을 관리하는 경우 사용자가 실행할 수 있는 모델을
availableModels에 추가하거나 모든 폴백을 차단하는deniedModels항목의 범위를 좁히세요. 특정 모델 또는 버전 차단에서 Default 옵션이 단계적으로 낮아지는 방식을 설명합니다. - 설정을 관리하지 않는 경우 메시지를 관리자에게 보내세요. 사용자 자신의 설정 파일로는 관리형
availableModels또는deniedModels목록을 확장할 수 없습니다.
관리형 설정이 이 API 공급자를 허용하지 않음
조직의 관리형 설정이allowedProviders 목록을 설정했는데, 세션의 API 공급자가 목록에 없거나 세션이 해당 항목이 요구하는 방식으로 고정되지 않은 엔드포인트를 사용합니다. Claude Code는 시작 시, 로그인 전, 또는 세션이 다음에 API에 연결할 때 거부합니다. 메시지는 허용된 공급자로 시작합니다:
(allowedProviders lists only unrecognized entries)로 표시됩니다.
할 일:
- 메시지의
To continue:단계를 따르세요. - 설정을 관리하는 경우 메시지에서
Admins:로 시작하는 줄이 추가할 항목 또는 고정할 값을 명시하며,allowedProviders항목에서 어느 소스의env블록으로 고정할 수 있는지 설명합니다.
MCP 서버가 엔터프라이즈 관리 정책에 의해 차단됨
/mcp에서 서버의 Reconnect를 선택했거나 비활성화된 서버를 다시 켰는데, MCP 서버를 제한하는 설정이 해당 서버를 차단합니다. Claude Code는 연결을 거부하고 다음을 표시합니다:
- 사용자 자신의
~/.claude/settings.json또는 프로젝트의.claude/settings.json에 있는 것을 포함하여 서버와 일치하는deniedMcpServers항목 - 서버가 일치하지 않는
allowedMcpServers목록 mcp가 잠긴strictPluginOnlyCustomization으로,~/.claude.json및.mcp.json에 구성된 서버를 차단합니다- 서버가 claude.ai 커넥터인 경우
disableClaudeAiConnectors
- 사용자 자신의 사용자 및 프로젝트 설정 파일에서 이러한 설정이 있는지 확인하고 변경하거나 제거하세요.
- 사용자 자신의 설정으로 차단이 설명되지 않으면 관리자에게 어떤 관리형 설정이 서버를 차단하는지 문의하세요.
/mcp의 Reconnect 및 다시 활성화로 세션 중 정책 업데이트가 차단한 서버를 연결할 수 있었습니다.
MCP 서버 이름이 예약됨
이 메시지는 MCP 서버 중 하나를 명시하며, 해당 서버의 이름은 기본 제공 서버의 이름처럼 Claude Code가 예약한 이름 중 하나입니다:- 서버를 정의한 곳에서 서버 이름을 바꾸세요. 예를 들어
workspace를my-workspace로 바꿉니다. - 피해야 할 다른 예약된 이름은 MCP 구성 경고를 참조하세요.
관리형 설정 문서를 구문 분석할 수 없음
조직이 관리형 설정을 배포했는데 배포된 문서 중 하나가 존재하지만 JSON 객체로 구문 분석할 수 없으므로, Claude Code는 해당 문서가 담고 있는 정책 없이 실행하는 대신 시작 시 코드 1로 종료합니다. 줄은 메시지 앞에 실패한 소스를 명시합니다:managed-settings.json파일 또는managed-settings.d아래 드롭인 파일의 경로- macOS 관리 기본 설정 프로필,
per-user managed preferences또는device-level managed preferences - Windows 레지스트리 값,
Registry: HKLM\SOFTWARE\Policies\ClaudeCode\Settings
claude -p, Agent SDK 세션, 백그라운드 세션, 그리고 claude doctor를 포함한 대부분의 하위 명령에서 표시됩니다. 이 거부는 의도적으로 안전하게 실패(fail closed)하도록 설계되었습니다. Claude Code가 구문 분석할 수 없는 문서의 설정은 적용할 수 없으며, 그래도 시작하면 조직의 통제 없이 세션이 실행되기 때문입니다.
구문 분석 가능한 문서의 스키마 문제는 이 오류를 발생시키지 않습니다. Claude Code가 삭제한 항목 찾기에서 이 경우 Claude Code가 어떻게 처리하는지 다룹니다.
managed-settings.d/ 디렉터리가 존재하지만 목록을 읽을 수 없으면 Claude Code는 대신 Managed settings drop-in directory could not be read: 뒤에 근본 오류를 보고합니다. Claude Code가 삭제한 항목 찾기에서 읽기 실패로 시작 시 종료되는 경우를 다룹니다.
할 일:
- 머신을 관리하는 경우 명시된 문서가 JSON 객체로 구문 분석되도록 수정하거나 파일, 프로필 또는 레지스트리 값을 제거하세요. 빈
managed-settings.json은{}로 간주되며 실행을 차단하지 않습니다. - 관리하지 않는 경우 관리자에게 배포된 문서를 수정하도록 요청하세요. 사용자 자신의 설정 파일은 이 오류를 일으키지도 해결하지도 않습니다.
관리 정책 설정을 읽을 수 없음
조직이 관리형 설정을 배포했는데, 배포된 소스 중 하나가 존재하지만 운영 체제가 읽기를 거부한 것이 아니라 I/O 오류 같은 이유로 읽을 수 없습니다. 다른 관리자 소스가 정책을 제공하지 않으면, Claude Code는 해당 소스가 담고 있을 수 있는 정책 없이 실행하는 대신 시작 시 종료합니다:claude gateway 서버는 allowedProviders를 명시하는 첫 번째 줄의 변형 메시지와 함께 거부됩니다.
루트 전용 파일처럼 운영 체제가 읽기를 거부한 경우에는 이 종료가 발생하지 않으며, 세션은 해당 소스의 정책 없이 시작됩니다. 구문 분석할 수 없는 소스의 경우 Claude Code는 소스를 명시하는 다른 메시지와 함께 종료합니다.
할 일:
- 머신을 관리하는 경우
Detail:줄이 명시한 문제를 수정하여 배포된 소스를 읽을 수 있게 하거나 소스를 제거하세요. - 관리하지 않는 경우 메시지를 관리자에게 보내세요. 사용자 자신의 설정 파일은 이 오류를 일으키지도 해결하지도 않습니다.
Managed settings contain invalid entries, including PreToolUse/PermissionRequest hooks that are NOT loaded
-p 실행에서 출력되는 이 stderr 블록은 관리형 설정 소스에 Claude Code가 로드할 수 없는 훅 항목이 있다는 의미입니다. 해당 훅은 실행되지 않으며, 어떤 줄에서 소스의 hooks 필드가 무시된 것으로 나열되면 해당 소스의 훅은 하나도 실행되지 않습니다.
각 줄은 소스, 필드(있는 경우), 그리고 알 수 없는 훅 type이나 hooks 키 외부에 선언된 훅 같은 문제를 명시합니다:
- 소스를 관리하는 경우 블록에 나열된 각 항목을 수정하거나 제거하세요. 훅 구성에서 Claude Code가
hooks아래에 기대하는 형태를 확인할 수 있습니다. - 줄의 소스가
parent managed settings이면 Claude Code를 실행한 애플리케이션이 해당 항목을 상위 설정으로 전달한 것이므로, 해당 애플리케이션의 개발자에게 보고하세요. - 그 외의 경우 블록을 관리자에게 보내세요.
-p 실행에서 이 경우가 Managed settings failed to load; policies from the failed source are NOT in effect: 헤더 아래에 나열되었습니다.
otelHeadersHelper 실패
Claude Code는otelHeadersHelper 스크립트가 실패하거나 스크립트 요구 사항을 충족하지 않는 출력을 내보낼 때, 대화형 세션당 한 번 터미널 인터페이스에 알림으로 이 경고를 표시합니다.
스크립트가 계속 실패하는 동안 내보내기가 실패하며 텔레메트리 백엔드는 세션에서 아무것도 받지 못합니다.
See /status: 뒤의 텍스트는 스크립트의 종료 코드와 그 뒤의 오류 출력처럼 무엇이 실패했는지를 나타냅니다:
/status를 실행하여 실패 세부 정보를 확인하세요.- 스크립트가 30초 이내에 0으로 종료되고 stdout에 문자열 헤더 값으로 이루어진 JSON 객체를 출력하도록 수정하세요. 스크립트 요구 사항을 참조하세요.
- 조직이 관리형 설정을 통해 스크립트를 배포하는 경우 이를 유지 관리하는 담당자에게 수정을 요청하세요.
-p를 사용하는 비대화형 모드에서는 같은 실패가 대신 stderr에 otelHeadersHelper failed (OpenTelemetry export headers unavailable): <error>로 나타납니다.
headersHelper 실행되지 않음
Claude Code는 MCP 서버를 정적headers만으로 연결했으며 서버의 headersHelper를 건너뛰었습니다. 헬퍼는 셸 명령인데 해당 폴더에 저장된 신뢰가 없기 때문입니다. 폴더는 ~/.claude.json에서 해당 항목을 직접 설정하거나, 홈 디렉터리 외부에서는 대화형 세션에서 신뢰 대화 상자를 수락할 때 저장된 신뢰를 얻습니다. 이 검사가 어떤 서버에 적용되는지는 headersHelper가 실행되기 전에 폴더 신뢰를 참조하세요.
Claude Code는 비대화형 모드에서만 서버당 한 번 이 줄을 기록합니다. 대화형 세션에서는 같은 거부를 대신 디버그 로그에 기록합니다.
projects 키는 프로젝트 허용 규칙 및 워크스페이스 신뢰에서 설명하는, Claude Code가 신뢰의 기준으로 삼는 폴더입니다. 상위 폴더에 대한 신뢰 대화 상자를 수락해도 이 검사를 통과하지 못하며, -p 또는 SDK 세션으로도 통과하지 못합니다.
할 일:
- 메시지가 명시한 폴더에서
claude를 실행하고 신뢰 대화 상자를 수락한 후-p또는 SDK 명령을 다시 실행하세요. - 메시지가 출력하는 정확한
projects키를 사용하여~/.claude.json에hasTrustDialogAccepted항목을 직접 설정하세요. - 홈 디렉터리에서 세션을 시작했다면 신뢰한 프로젝트 디렉터리에서 작업하세요. 홈 디렉터리에서 신뢰 대화 상자를 수락하면 Claude Code는 현재 세션에만 해당 신뢰를 유지합니다.
잘못된 형식의 Tool(content) 규칙
설정 파일 중 하나의 권한 규칙이Tool 또는 Tool(content) 형태가 아닙니다. 예를 들어 닫는 괄호 뒤에 텍스트가 있거나 괄호 중 하나가 누락된 경우입니다. Claude Code는 규칙을 건너뛰고, 대화형 세션이 시작될 때 유효하지 않은 설정 대화 상자와 claude doctor 출력에 해당 규칙을 나열합니다:
- 메시지와 함께 나열된 설정 파일에서 규칙이 닫는 괄호에서 끝나도록 다시 작성하세요. 예를 들어
Bash(ls) x대신Bash(ls *)를 사용합니다. - 내용 안의 괄호는 그대로 두세요. 괄호는 리터럴로 처리되므로
Edit(./Finance (2024)/**)같은 규칙은 이스케이프 없이도 유효합니다.
Mismatched parentheses로 보고했습니다.
Matches no tool · check for typos
시작 배너 아래의 이 행은 Claude Code가 도구 이름을 인식하지 못하는 거부 또는 확인 권한 규칙을 명시하며, 해당 규칙은 의도한 도구에 적용되지 않습니다.Bsh로 작성한 거부 규칙은 Bash에 적용되지 않으며, 도구의 표준 이름 대신 트랜스크립트에 표시되는 레이블을 사용한 규칙도 마찬가지입니다. 행은 작성한 그대로의 규칙을 반복해서 보여 줍니다:
- 규칙의 도구 이름을 수정하세요. 예를 들어
Bsh대신Bash를 사용합니다. 표준 이름은 도구 참조에서 확인하세요. - 규칙이 정의된 위치를 찾으려면 세션에서
/permissions를 실행하고 규칙을 선택하세요. 세부 정보에From project local settings, 또는--disallowedTools값의 경우From CLI argument처럼 규칙의 출처가 표시됩니다. - 세부 정보가
From enterprise managed settings로 표시되면 사용자가 직접 해당 규칙을 변경할 수 없으므로 관리형 설정을 유지 관리하는 담당자에게 해당 행을 전달하세요.
--output-format json이나 stream-json을 사용하는 경우, Claude Code는 경고를 stderr 대신 디버그 로그에 기록합니다. --debug로 실행하면 ~/.claude/debug/<session-id>.txt에서 확인할 수 있습니다.
v2.1.305 이전에는 대화형 세션이 행을 표시하는 대신 시작 시 더 긴 형태의 경고를 stderr에 출력했습니다.
파일 권한 검사와 일치하지 않음
Claude Code는 설정 파일, 관리형 설정, 또는--allowedTools, --disallowedTools, --settings 플래그 값에서 경로가 포함된 Write, NotebookEdit, MultiEdit, 또는 Glob 권한 규칙을 찾았습니다. Claude Code는 파일 권한을 Edit 및 Read 규칙에 대해서만 검사하므로, 다른 파일 도구를 명시하는 경로 규칙은 전혀 참조하지 않습니다. 규칙은 유지되며 다른 것은 변경되지 않습니다.
-
대화형 세션: 전체 경고는 디버그 로그에 기록되며, 이 형태의 거부 또는 확인 규칙은 시작 배너 아래에 다음 행으로도 표시됩니다:
이 형태의 허용 규칙은 행이 표시되지 않습니다. 규칙이 정의된 위치를 찾으려면 세션에서
/permissions를 실행하고 규칙을 선택하세요. -
텍스트 출력을 사용하는 비대화형 모드: stderr의 전체 경고는 규칙, 괄호 안의 소스, 그리고 대신 작성할 규칙을 명시합니다:
-
백그라운드 세션, 또는
--output-format json이나stream-json: 기계가 읽는 출력을 깨끗하게 유지하기 위해 전체 경고는 stderr 대신 디버그 로그에 기록됩니다.--debug로 실행하면~/.claude/debug/<session-id>.txt에서 확인할 수 있습니다.
Write(path),NotebookEdit(path), 레거시MultiEdit(path)규칙을Edit(path)로 바꾸세요.Edit규칙은 모든 파일 편집 도구에 적용됩니다.- Claude Code가 경고 없이
Glob규칙을 수락하는--allowedTools를 제외하고,Glob(path)규칙을Read(path)로 바꾸세요. - 전체 경고가 괄호 안에 명시한 소스에서 규칙을 수정하세요: 설정 파일 경로, 또는
--allowed-tools및--disallowed-tools의 경우 플래그 자체입니다. 디스크에 존재하지 않는claude-settings-<hash>.json경로는 인라인--settings값을 나타냅니다. 해당 플래그에 전달하는 JSON을 수정하세요. Write또는Glob같은 도구 이름만 있는 규칙은 그대로 두세요. Claude Code는 이러한 규칙을 도구 수준에서 일치시키며 경고하지 않습니다.- 관리형 설정의 규칙인 경우 전체 경고의 괄호 안에
managed policy settings가 표시되고/permissions의 규칙 세부 정보에From enterprise managed settings가 표시됩니다. 사용자가 직접 해결할 수 없으므로 관리형 설정을 유지 관리하는 담당자에게 해당 경고를 전달하세요.
명령의 나머지 부분 앞에 와일드카드가 있음
Claude Code는 설정 파일, 관리형 설정, 또는--allowedTools나 --settings 플래그 값에서 Bash(git * main) 또는 Bash(git -C * status *)처럼 *가 어떤 명령인지를 결정하는 뒤쪽 단어보다 앞에 오는 Bash 허용 규칙을 찾았습니다. *는 해당 위치에 삽입된 옵션을 포함한 모든 텍스트와 일치합니다. 예를 들어 Bash(git * main)은 git -c core.fsmonitor=<script> diff main도 승인하는데, 여기서 -c는 git이 명령에 지정된 프로그램을 실행하게 만듭니다. 와일드카드 패턴에서 일치 규칙을 확인할 수 있습니다.
이 경고는 의도보다 넓은 와일드카드를 가진 규칙의 범위를 좁힐 수 있도록 하기 위한 것입니다. Claude Code는 규칙을 유지하며 일치 방식도 변경하지 않습니다. 텍스트 출력을 사용하는 비대화형 모드에서는 stderr의 경고가 규칙과 괄호 안의 소스를 명시합니다:
/permissions를 실행하고 규칙을 선택하세요.
할 일:
- 하위 명령 앞의
*를 의도한 정확한 값으로 바꾸세요:Bash(git * main)대신Bash(git checkout main). - 모든
*를 하위 명령 뒤로 옮기세요:Bash(git -C * status *)대신Bash(git status *). 허용하려는 하위 명령마다 규칙을 하나씩 작성하세요. - 전체 경고가 괄호 안에 명시한 소스에서 규칙을 수정하세요: 설정 파일 경로 또는
--allowed-tools플래그 자체입니다. 디스크에 존재하지 않는claude-settings-<hash>.json경로는 인라인--settings값을 나타냅니다. 해당 플래그에 전달하는 JSON을 수정하세요. - 관리형 설정의 규칙인 경우 전체 경고의 괄호 안에
managed policy settings가 표시되고/permissions의 규칙 세부 정보에From enterprise managed settings가 표시됩니다. 사용자가 직접 해결할 수 없으므로 관리형 설정을 유지 관리하는 담당자에게 해당 경고를 전달하세요.
--output-format json이나 stream-json을 사용하는 경우, Claude Code는 기계가 읽는 출력을 깨끗하게 유지하기 위해 경고를 stderr 대신 디버그 로그에 기록합니다. --debug로 실행하면 ~/.claude/debug/<session-id>.txt에서 확인할 수 있습니다. v2.1.246 이전에는 Claude Code가 경고 없이 이러한 규칙을 수락했습니다.
v2.1.305 이전에는 대화형 세션이 행을 표시하는 대신 전체 경고를 stderr에 출력했습니다.
Bash를 거부하면 PowerShell 도구도 꺼짐
예를 들어--disallowedTools Bash를 사용하거나 설정 파일 중 하나에 Bash 또는 Bash(*)만 있는 거부 규칙을 사용하여 Bash 도구 전체를 제거했습니다. Git Bash가 설치된 Windows에서는 Bash를 거부하면 PowerShell 도구도 꺼지므로 세션이 셸 도구 없이 시작됩니다.
텍스트 출력을 사용하는 비대화형 모드에서는 Claude Code가 시작 시 stderr에 이 경고를 출력하며, 대화형 세션에서는 디버그 로그에만 기록합니다:
- Claude가 PowerShell을 사용하도록 하려면 PowerShell 도구 활성화에 나온 대로 환경 또는 설정 파일의
env블록에서CLAUDE_CODE_USE_POWERSHELL_TOOL을1로 설정하세요. 그러면 PowerShell 도구는 Bash 거부 규칙과 함께 켜진 상태로 유지됩니다. - 도구 전체 대신 특정 명령을 차단하려면 같은 설정 파일 또는 플래그에서
Bash만 있는 항목을Bash(git push *)같은 범위가 지정된 규칙으로 바꾸세요. Claude는 Bash 도구를 유지하며, PowerShell 도구는 변수를 설정하거나 범위가 지정된PowerShell권한 규칙을 추가할 때까지 꺼진 상태로 유지됩니다.
--output-format json이나 stream-json을 사용하는 경우, Claude Code는 경고를 stderr 대신 디버그 로그에 기록합니다. --debug로 실행하면 ~/.claude/debug/<session-id>.txt에서 확인할 수 있습니다. v2.1.287 이전에는 Claude Code가 경고를 출력하지 않고 같은 방식으로 PowerShell 도구를 껐습니다.
v2.1.305 이전에는 대화형 세션도 시작 시 경고를 stderr에 출력했습니다.
crossSessionInbound는 accept, hold, refuse 중 하나여야 함
설정 파일이crossSessionInbound를 오타 "reject"처럼 Claude Code가 인식하지 못하는 값으로 설정했습니다. 경고의 두 번째 문장은 어느 파일에 값이 있는지에 따라 다르며, 사용자, 프로젝트, 로컬 또는 --settings 파일에서는 다음과 같습니다:
refuse로 취급하며, 경고는 관리자가 수정할 때까지 세션 간 메시지가 거부된다고 알립니다. 보류가 다른 설정 파일의 값과 어떻게 결합되는지는 crossSessionInbound를 참조하세요.
할 일:
- 키를
"accept","hold", 또는"refuse"로 설정하거나 제거하세요. - 경고가 관리형 설정을 명시하면 관리자에게 값을 수정하도록 요청하세요.
ANTHROPIC_FOUNDRY_RESOURCE는 Foundry 리소스 이름이어야 함
ANTHROPIC_FOUNDRY_RESOURCE를 엔드포인트 URL이나 해당 호스트 이름처럼 순수한 Microsoft Foundry 리소스 이름이 아닌 값으로 설정했습니다. Claude Code는 요청을 보내기 전에 해당 값을 거부했습니다. 이 메시지는 시작 경고가 아니라 Claude의 응답 대신 나타납니다:
ANTHROPIC_FOUNDRY_RESOURCE를 리소스 이름만으로 설정하고 Claude Code를 다시 시작하세요. 엔드포인트https://my-resource.services.ai.azure.com/anthropic의 경우 이름은my-resource입니다.- 대신 전체 엔드포인트 URL을 지정하려면
ANTHROPIC_FOUNDRY_BASE_URL을 해당 URL로 설정하고ANTHROPIC_FOUNDRY_RESOURCE를 제거한 후 Claude Code를 다시 시작하세요. Claude Code는 두 변수 중 하나만 허용합니다.
200K 제한이 적용되지 않음
CLAUDE_CODE_DISABLE_1M_CONTEXT=1을 설정하면 일반적으로 자동 압축이 1M 컨텍스트 모델의 세션을 200K 윈도우로 유지하지만, 이 세션을 200K 이하로 제한하는 압축 임계값이 없으므로 대화가 200K를 넘어 커질 수 있습니다.
- 모델 ID가 LLM 게이트웨이 별칭처럼 Claude Code가 인식하지 못하는 것이고,
CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1을 설정했거나CLAUDE_CODE_MAX_CONTEXT_TOKENS로 가정 윈도우를 200K 이상으로 올린 경우. 이 경우 메시지는 해결책으로or update to a Claude Code version that recognizes <model>도 제시합니다. ANTHROPIC_BETAS또는--betas플래그로 요청한context-1m베타가 해당 베타를 지원하는 모델에서 여전히 API에 1M 윈도우를 요청하는 반면, 200K에서 세션을 압축하는 것이 없는 경우
CLAUDE_CODE_AUTO_COMPACT_WINDOW=200000을 설정하거나autoCompactWindow설정을200000으로 설정하여 자동 압축이 200K 경계에서 압축하도록 하세요.- 메시지가 이 버전이 인식하지 못하는 모델 ID를 명시하면
claude update를 실행하세요. 해당 ID를 1M 컨텍스트 모델로 인식하는 버전은 추가 구성 없이 제한을 적용합니다. - 세션이 대신 모델의 전체 윈도우를 사용하기를 원하면
CLAUDE_CODE_DISABLE_1M_CONTEXT를 설정 해제하세요. 이 경고는 200K 제한이 적용되지 않는다는 사실만 알립니다.
--output-format json이나 stream-json을 사용하는 경우에는 대신 디버그 로그에 기록됩니다. --debug로 실행하면 ~/.claude/debug/<session-id>.txt에서 확인할 수 있습니다.
v2.1.305 이전에는 대화형 세션이 시작 시 경고를 stderr에 출력했습니다.
요청에서 인식되지 않은 모델 ID
Claude Code가 사용 중인 Claude Code 버전이 인식하지 못하는 모델 ID로 요청을 보냈으며, 해당 ID를 인식하는 모델에 매핑하는modelOverrides 항목을 찾지 못했습니다. Claude Code는 여전히 구성된 그대로의 ID로 요청을 보내며, 종료하거나 모델을 전환하지 않습니다.
[claude-code:unrecognized_model] 접두사로 일치시키세요. 접두사와 공백 하나 뒤에 Claude Code는 한 줄짜리 JSON 객체를 기록합니다. Claude Code는 이후 버전에서 필드를 추가할 수 있으므로 예상하지 못한 필드는 무시하세요. 최소한 다음 두 필드는 기록됩니다:
model: 구성된 그대로의 모델 문자열query_source: 모델을 사용한 요청 경로. 예를 들어-p실행의 주 대화에서는 값이sdk이고, 서브에이전트의 경우agent:로 시작합니다.
-p를 사용하는 비대화형 모드에서는 모든--output-format에서 stderr에 기록하므로, 이 줄을 걸러내지 않고도 stdout을 구문 분석할 수 있습니다.- 대화형 세션 또는 백그라운드 세션에서는 대신 디버그 로그에 기록합니다.
--debug로 실행하면~/.claude/debug/<session-id>.txt에서 확인할 수 있습니다.
us.anthropic.claude-... ID, @ 버전 접미사가 있는 Google Cloud의 Agent Platform ID, Claude 모델 ID를 포함하는 Microsoft Foundry 배포 이름처럼 인식하는 모델로 해석되는 공급자 ID에 대해서는 이 줄을 기록하지 않습니다. Amazon Bedrock 애플리케이션 추론 프로필 ARN의 경우 ARN 자체가 아니라 그 뒤의 모델을 확인합니다. 잘못 입력한 ARN처럼 해석할 수 없는 ARN에 대해서는 줄을 기록하지 않습니다.
할 일:
-
LLM 게이트웨이 별칭처럼 ID를 의도적으로 설정한 경우, 해당 ID를 값으로 하는
modelOverrides항목을 설정 파일에 추가하세요. 키로는opus같은 패밀리 별칭이 아닌 Anthropic 모델 ID를 사용하세요. 예시 줄의my-proxy-model에 대해서는 다음 항목을 추가합니다:그러면 Claude Code는my-proxy-model을claude-opus-4-6으로 취급하고 줄 기록을 중지합니다. -
ID가 사용 중인 Claude Code 버전보다 최신 모델을 가리키면
claude update를 실행하세요. -
ID가 오타인 경우 모델을 설정할 수 있는 위치 또는 별칭 변수 중 해당 ID가 있는 곳에서 수정하세요.
query_source가agent:로 시작하면 대신 서브에이전트의 모델을 설정한 곳에서 수정하세요.
관리형 잠금에서 샌드박스 허용 항목이 무시됨
/status 및 claude doctor의 이 경고는 관리형 설정이 allowManagedReadPathsOnly 또는 allowManagedDomainsOnly를 설정했으므로, 경고가 명시한 파일의 allowRead 또는 allowedDomains 항목이 적용되지 않는다는 의미입니다:
sandbox.network.allowedDomains와 allowManagedDomainsOnly를 명시하고, only allowed domains (and WebFetch domain rules) from managed settings are honored라고 알립니다.
할 일:
- 이 경고에 대해 조치할 필요는 없습니다.
- 해당 경로나 도메인이 필요하고 조직의 관리형 설정이 잠금을 설정한 경우 관리자에게 해당 설정에 추가하도록 요청하세요. 명시된 파일에서 항목을 제거하기 전까지 경고는 계속 표시됩니다.
- 경고를 없애려면 명시된 파일에서 항목을 제거하세요. 프로젝트의
.claude/settings.json처럼 공유하는 파일의 경우, 잠금이 없는 팀원을 위해 항목을 그대로 두고 경고가 표시되도록 둘 수 있습니다.
쓰기 거부 경로에 남은 샌드박스 마스크 파일
claude doctor 및 /status의 이 경고는 마스크 파일, 즉 샌드박스가 쓰기를 거부하는 경로에 있는 0바이트 읽기 전용 자리 표시자 파일을 나열합니다. 이 경고는 Linux 및 WSL2에서 파일 시스템 격리가 켜진 상태로 샌드박싱이 활성화된 경우에 나타납니다. 해당 파일이 있는 프로젝트에 열려 있는 Claude Code 세션이 없을 때 셸에서 삭제하세요.
샌드박스는 샌드박스된 명령이 실행되는 동안 자리 표시자를 만들고 명령이 끝나면 제거합니다. 다음과 같은 경우에는 자리 표시자가 남습니다:
- 명령이 끝나기 전에 SIGKILL 등으로 세션이 강제 종료된 경우
- 백그라운드에서 실행 중인 명령처럼 샌드박스된 명령이 아직 실행 중인 상태에서 세션을 종료한 경우
claude doctor에서 경고는 다음과 같이 표시됩니다:
/status에 경고가 표시된 세션을 포함하여 나열된 파일이 있는 프로젝트에 열려 있는 모든 Claude Code 세션을 종료한 다음 셸에서 작업하세요. 다른 세션의 샌드박스가 아직 사용 중인 자리 표시자는 해당 세션의 쓰기 보호에서 실제로 작동하는 부분입니다.- 셸에서 나열된 각 파일을
rm으로 삭제하고,rm이 쓰기 보호된 파일에 대해 물으면 확인하세요. 경고는 최대 3개의 파일을 명시하고 나머지는 개수로 표시하므로, 삭제 후 경고가 더 이상 나타나지 않을 때까지claude doctor를 다시 실행하세요. - “Yes, and don’t ask again”으로 저장한 권한 선택이 유지되지 않았다면 자리 표시자를 삭제한 후 다시 저장하세요.
Stale sandbox mask files left by a killed session으로 표시되었습니다.
v2.1.257 이전에는 claude doctor가 이러한 파일을 표시하지 않았으며, 이전 버전에서도 세션이 강제 종료되면 같은 자리 표시자가 남습니다.
Claude Code 설정 파일이 두 개 존재함
Claude Code는 이 메시지가 명시한 첫 번째 파일을 사용하고 있으므로 두 번째 파일의 내용은 적용되지 않습니다. 첫 번째 파일은.claude.json의 이전 이름인 .config.json입니다. 메시지에는 어느 파일에 사용자의 설정이 들어 있는지 확인하는 방법이 포함되어 있습니다:
grep 명령이 포함된 문장 대신 The one with hasCompletedOnboarding or mcpServers in it is usually yours.가 표시됩니다.
할 일:
1
설정이 들어 있는 파일 찾기
- Windows: 두 파일을 모두 열고 어느 파일에
hasCompletedOnboarding또는mcpServers가 들어 있는지 확인하세요 - 기타 플랫폼: 셸에서 메시지의
grep명령을 실행하고 어느 파일의 개수가 더 높은지 확인하세요
2
홈 디렉터리를 공유하는 모든 호스트 업데이트
여러 호스트가 이 홈 디렉터리를 공유하는 경우, 먼저 모든 호스트의 Claude Code를 메시지가 명시한 버전 이상으로 업데이트하세요.
3
Claude Code 중지
모든 호스트에서 Claude Code 프로세스를 중지하세요.
4
원하지 않는 파일 옮기기
원하지 않는 파일을 해당 폴더 밖으로 옮기세요. 나중에 되돌릴 수 있도록 삭제하지 말고 옮기세요.
5
Claude Code를 다시 시작하기 전에 기다리기
옮긴 파일이 이전 경로에 있다고 표시하는 호스트가 하나도 남지 않을 때까지 어느 호스트에서도 Claude Code를 시작하지 마세요.
나중에 이 변경을 다시 수행하세요: ~/.claude.json을 업데이트할 수 없음
stderr의 이 알림은 로그인이나 신뢰 프롬프트에 대한 응답처럼~/.claude.json에 대한 변경 사항이 파일에 저장되지 않았다는 의미입니다:
- 이후 세션에서 변경을 다시 수행하세요. 예를 들어
/login을 다시 실행하거나 신뢰 프롬프트에 다시 응답하세요.
응답 품질이 평소보다 낮아 보입니다
Claude의 답변이 예상보다 덜 능력 있어 보이지만 오류가 표시되지 않는 경우, 원인은 일반적으로 모델 자체가 아니라 대화 상태입니다. Claude Code는 모델 버전을 자동으로 변경하지 않습니다. 다음의 경우에 폴백 모델로 전환할 수 있습니다:- 구성된
--fallback-model은 가용성 오류 후 해당 턴에만 제어를 인수받으며, 트랜스크립트에 공지가 표시됩니다 - Amazon Bedrock 또는 Google Cloud의 Agent Platform 시작 확인에서 기본 모델을 사용할 수 없음을 발견하거나, 계정이 세션 중간에 모델에 대한 액세스를 잃음
- Fable 모델, Opus 5.5, Sonnet 5.5, Opus 5의 자동 모델 폴백은 플래그된 카테고리에 폴백 모델이 있는 경우 세션을 해당 카테고리의 폴백 모델로 이동합니다. 트랜스크립트에 공지가 표시됩니다
/model 변경이 아니라 트랜스크립트 공지로 나타납니다. 모델 구성에서 각 폴백이 적용되는 시기를 설명합니다.
먼저 다음을 확인하십시오:
- 모델 선택:
/model을 실행하여 예상하는 모델에 있는지 확인합니다. 이전/model선택 또는ANTHROPIC_MODEL환경 변수로 인해 의도한 것보다 작은 모델에 있을 수 있습니다. - 노력 수준:
/effort를 실행하여 현재 추론 수준을 확인하고 어려운 디버깅 또는 설계 작업을 위해 높입니다. 기본값은 모델에 따라 다르므로 최대값 이하에 있다고 가정하기 전에 확인하십시오. 노력 수준 조정에서 모델별 기본값과ultrathink바로가기를 참조하십시오. - 컨텍스트 압력:
/context를 실행하여 윈도우가 얼마나 찼는지 확인합니다. 용량에 가까우면 자연스러운 지점에서/compact를 실행하거나/clear를 실행하여 새로 시작합니다. 컨텍스트 윈도우 탐색에서 자동 압축이 이전 턴에 어떻게 영향을 미치는지 확인하십시오. - 오래된 지침: 크거나 오래된
CLAUDE.md파일과 MCP 도구 정의는 컨텍스트를 소비하고 응답을 조종할 수 있습니다./doctor점검은 크기가 큰 메모리 파일과 사용하지 않는 확장을 플래그하며,/context는 MCP 도구 토큰 사용량을 표시합니다. v2.1.205 이전에는/doctor가 크기가 큰 메모리 파일과 서브에이전트 정의를 플래그하는 진단 화면을 열었습니다.
/rewind를 실행하여 잘못된 턴 이전으로 돌아간 다음 더 구체적인 내용으로 프롬프트를 다시 표현합니다. 스레드 내에서 수정하면 잘못된 시도가 컨텍스트에 남아 있어 나중의 답변을 고정할 수 있습니다. 체크포인팅을 참조하십시오.
위의 항목을 확인한 후에도 품질이 여전히 좋지 않으면 /feedback을 실행하고 예상한 것과 얻은 것을 설명합니다. 이 방식으로 제출된 피드백에는 대화 트랜스크립트가 포함되어 있으며, 이는 Anthropic이 실제 회귀를 진단하는 가장 빠른 방법입니다. 환경에서 /feedback을 사용할 수 없는 경우 오류 보고를 참조하십시오.
Claude가 의심되는 프롬프트 주입에 대해 경고하거나 의심되는 주입으로 인해 요청을 거부하고, 경고가 명명하는 텍스트가 파일 또는 웹 콘텐츠가 아니라 Claude Code가 대화에 자동으로 추가하는 컨텍스트인 경우 claude update를 실행하고 다시 시도합니다. 업데이트 후 경고가 반복되면 플래그된 콘텐츠를 프롬프트에 다시 붙여넣는 대신 보고합니다. v2.1.201 이전에는 Sonnet 5가 같은 방식으로 일부 요청을 거부했습니다.
오류 보고
이 페이지에서 다루지 않는 구성 요소의 오류는 관련 가이드를 참조하십시오:- MCP 서버 연결 또는 인증 실패: MCP
- 훅 스크립트 실패 또는 도구 차단: 훅 디버깅
- 설치 중 권한 거부 또는 파일 시스템 오류: 설치 및 로그인 문제 해결
- Claude Code 내에서
/feedback을 실행하여 기록 및 설명을 Anthropic에 전송하십시오. 이 명령은 미리 작성된 GitHub 이슈를 열 수 있는 옵션도 제공합니다. Anthropic에 전송하려면 인증이 필요합니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 및 기타 타사 제공자에서 또는 Anthropic 자격 증명이 구성되지 않은 경우,/feedback은 대신 Anthropic 계정 담당자에게 보낼 수 있는 로컬 아카이브를 저장합니다. /feedback이 조직의 정책에 의해 비활성화되었다고 응답하는 경우 해당 메시지 항목을 참조하십시오- 셸에서
claude doctor를 실행하여 설치의 읽기 전용 진단을 수행하거나, Claude Code 내에서/doctor점검을 실행하여 설정 문제를 찾고 수정하십시오 - status.claude.com에서 활성 인시던트를 확인하십시오
- GitHub의 기존 이슈를 검색하십시오