" (the advisor must be at least as capable as the main model). The advisor will not be used for the main model.`가 표시되며, 세션은 그대로 시작됩니다. **할 일:** * 더 높은 순위의 advisor 또는 더 낮은 순위의 메인 모델을 선택합니다. [advisor 모델 선택](/docs/ko/advisor#choose-an-advisor-model)에서 순위와 각 메인 모델에 허용되는 advisor 목록을 확인할 수 있습니다. * advisor가 조언할 수 있는 모델을 사용하는 [서브에이전트](/docs/ko/sub-agents)가 계속 advisor를 사용하도록 하려면 advisor 설정을 그대로 둡니다. v2.1.287 이전에는 Claude Code가 여러 조합의 순위를 다르게 매겼습니다. Opus 4.7 또는 Opus 4.8 메인 모델에 Sonnet 5.5 advisor를 사용할 때 이 메모를 표시했지만, 이 조합은 이제 허용됩니다. 또한 Sonnet 5.5 메인 모델에 Opus 4.8 advisor를 사용하는 경우처럼 현재는 이 메모가 표시되는 일부 advisor를 연결했습니다.

thinking.type.enabled is not supported for this model

Claude Code 버전이 선택한 모델의 최소 버전보다 오래되었습니다. CLI가 모델이 더 이상 허용하지 않는 사고 구성을 보냈습니다. ```text theme={null} API Error: 400 ... "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior. ``` **할 일:** * `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 릴리스 채널](/docs/ko/setup#configure-release-channel)에서는 업데이트해도 최신 stable 릴리스 이후로는 이동하지 않으며, 이 릴리스는 여전히 이러한 버전보다 오래되었을 수 있습니다. latest 채널로 이동한 다음 업데이트합니다. * 업그레이드할 수 없으면 `/model`을 실행하고 대신 Opus 4.6 또는 Sonnet 4.6을 선택합니다. * [Agent SDK](/docs/ko/agent-sdk/overview)에서 이 오류가 발생하면 대신 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를 사용할 수 없습니다

[확장 사고](/docs/ko/model-config#extended-thinking)를 끄고 `high`보다 높은 [effort 수준](/docs/ko/model-config#adjust-effort-level)으로 실행했습니다. 모델이 해당 조합을 허용하지 않으므로 API가 요청을 거부했습니다. ```text theme={null} API Error: Effort 'xhigh' isn't available with thinking turned off on this model · run /effort high to continue, or turn thinking back on (unset MAX_THINKING_TOKENS=0) ``` `·` 뒤의 힌트는 세션에 따라 다릅니다: 비대화형 세션에서는 `use --effort high (or the effortLevel setting)`로, Claude Desktop 앱이 실행하는 세션에서는 `you can lower effort to High`로 표시됩니다. **할 일:** * [effort 수준을 낮춰](/docs/ko/model-config#set-the-effort-level) `high` 이하로 설정합니다. * 사고를 다시 켭니다. 예를 들어 [`MAX_THINKING_TOKENS`](/docs/ko/env-vars) 설정을 해제하거나 설정에서 [`"alwaysThinkingEnabled": false`](/docs/ko/settings-reference#alwaysthinkingenabled)를 제거합니다. v2.1.242 이전에는 Claude Code가 API 자체의 메시지를 표시했습니다: `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`를 보냅니다.

사고 예산이 출력 제한을 초과합니다

구성된 확장 사고 예산이 최대 응답 길이를 초과하므로 실제 답변을 위한 공간이 남지 않습니다. ```text theme={null} API Error: 400 ... max_tokens must be greater than thinking.budget_tokens ``` **할 일:** * [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](/docs/ko/env-vars)를 사고 예산보다 높게 올립니다. * 예산이 출력 길이와 상호 작용하는 방식은 [확장 사고](/docs/ko/model-config#extended-thinking)를 참조하십시오.

도구 사용 또는 thinking 블록 불일치

대화 기록이 일관성 없는 상태로 API에 도달했습니다. ```text theme={null} API Error: 400 due to tool use concurrency issues. Run /rewind to recover the conversation. API Error: 400 orphaned tool_result in conversation history. Run /rewind to recover the conversation. API Error: 400 duplicate tool_use ID in conversation history. Run /rewind to recover the conversation. API Error: 400 ... unexpected `tool_use_id` found in `tool_result` blocks API Error: 400 ... thinking blocks ... cannot be modified ``` 모든 변형은 동일한 의미입니다: 기록의 `tool_use`, `tool_result` 및 `thinking` 블록의 순서가 더 이상 API가 예상하는 것과 일치하지 않습니다. **할 일:** * Opus 4.7 또는 Opus 4.8을 사용하는 경우 먼저 `claude update`를 실행합니다. v2.1.156 이전 버전은 정상적인 도구 사용 중에 이 오류를 트리거할 수 있으며 `/rewind`로는 해결되지 않습니다. * `/rewind`를 실행하거나 Esc를 두 번 눌러 손상된 턴 이전의 체크포인트로 되돌아가 거기서 계속합니다. 체크포인트가 생성되고 복원되는 방식은 [체크포인트](/docs/ko/checkpointing)를 참조하십시오.

redacted\_thinking 블록의 유효하지 않은 데이터

대화 기록의 이전 턴에 포함된 `redacted_thinking` 블록을 API가 허용할 수 없기 때문에 400으로 요청을 거부했습니다. ```text theme={null} API Error: 400 ... Invalid `data` in `redacted_thinking` block ``` Claude Code는 대화의 이전 사고를 요청에서 제외하고 한 번 재시도하므로 세션은 오류를 표시하지 않고 계속됩니다. v2.1.282 이전에는 Claude Code가 거부된 블록을 유지했고 이후의 모든 턴이 동일한 오류로 실패했습니다. **할 일:** * v2.1.281 이하 버전을 사용 중이고 모든 턴이 이 오류로 실패하면 `claude update`를 실행하고 세션을 재개합니다. * 오류가 지속되면 `/clear`를 실행하여 해당 블록이 포함되지 않은 대화를 시작합니다.

Unsupported tool content removed

Claude Code가 Anthropic API에 직접 연결된 상태에서 저장된 세션을 로드하거나 미리 볼 때, Anthropic API가 허용하지 않는 도구 내용을 제거하고 제거된 내용이 두 thinking 블록 사이에 있던 위치에 이 줄을 남깁니다: ```text theme={null} [Unsupported tool content removed] ``` 이러한 내용은 Anthropic API가 아닌 다른 무언가가 API 형식으로 응답했을 때 세션 파일에 들어갑니다. 일반적으로 다른 제공자의 도구 호출을 변환하는, [`ANTHROPIC_BASE_URL`](/docs/ko/env-vars)로 설정된 타사 프록시입니다. 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으로 요청을 거부했습니다: ```text theme={null} API Error: 400 messages.6: role 'system' must precede an 'assistant' message or end the array; ... ``` Claude Code는 일부 리마인더 및 첨부 텍스트를 대화 내부의 시스템 메시지로 보냅니다. API가 그중 하나의 위치를 거부하면 Claude Code는 해당 텍스트를 일반 사용자 메시지로 대신 보내 요청을 한 번 재시도합니다. `use the top-level 'system' parameter for the initial system prompt`와 같은 API의 유사한 배치 관련 문구도 동일한 복구가 적용됩니다. 오류가 표시된다면 거부된 시스템 메시지는 Claude Code가 제거할 수 있는 것이 아닙니다. 이는 일반적으로 Claude Code와 API 사이의 프록시 또는 [LLM 게이트웨이](/docs/ko/llm-gateway)가 자체 시스템 메시지를 추가했음을 의미합니다. **할 일:** * [`ANTHROPIC_BASE_URL`](/docs/ko/env-vars)로 구성된 프록시 또는 게이트웨이 뒤에서 오류가 매 턴마다 반복되면 프록시 없이 연결하여 원인을 확인하고, 해당 프록시를 운영하는 담당자에게 오류를 보고합니다. * `/clear`를 실행하여 새 대화를 시작합니다. 거기서도 오류가 다시 발생하면 원인은 저장된 대화가 아닌 요청 경로에 있습니다. v2.1.280 이전에는 Claude Code가 이 문구를 인식하지 못했으므로 거부된 시스템 메시지가 Claude Code 자체가 보낸 것일 때도 오류가 표시되었고, 대화의 이후 모든 턴이 동일한 방식으로 실패했습니다.

search\_result 블록의 유효하지 않은 encrypted\_content

대화 기록에 API가 해독할 수 없는 호스팅 웹 검색 내용이 포함되어 있기 때문에 API가 400으로 요청을 거부했습니다. 문구는 읽을 수 없는 필드를 나타냅니다: ```text theme={null} API Error: 400 ... Invalid `encrypted_content` in `search_result` block API Error: 400 ... Invalid `encrypted_index` in `text` block API Error: 400 ... Failed to decrypt web search result content API Error: 400 ... Invalid `encrypted_stdout` in `encrypted_code_execution_result` block ``` API의 호스팅 [웹 검색 도구](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool) 결과에는 API만 읽을 수 있는 암호화된 필드가 포함됩니다. `encrypted_stdout` 문구는 이러한 결과를 읽은 호스팅 코드 실행 프로그램의 출력을 가리키며, API는 이 출력도 암호화합니다. API는 다른 조직을 위해 생성된 내용처럼 해독할 수 없는 내용을 다시 보내는 요청을 거부합니다. Claude Code 자체의 [WebSearch 도구](/docs/ko/tools-reference#websearch-tool-behavior)는 검색 결과를 일반 텍스트로 기록하므로, 이러한 블록은 일반적으로 호스팅 웹 검색을 자체적으로 실행한 프록시 또는 [LLM 게이트웨이](/docs/ko/llm-gateway)를 통해 대화에 들어옵니다. 세 가지 웹 검색 문구의 경우 Claude Code는 검색 호출, 결과 및 인용을 보내는 내용에서 제외하고 요청을 한 번 재시도하므로 세션은 오류를 표시하지 않고 계속됩니다. `encrypted_stdout` 문구에는 이러한 복구가 없으므로 해당 메시지는 여전히 표시됩니다. v2.1.282 이전에는 Claude Code가 거부된 웹 검색 블록도 유지했고, 이후의 모든 턴과 `/compact`가 동일한 방식으로 실패했습니다. **할 일:** * v2.1.281 이하 버전을 사용 중이고 모든 턴이 웹 검색 문구 중 하나로 실패하면 `claude update`를 실행하고 세션을 재개합니다. * 오류가 지속되거나 메시지가 `encrypted_stdout`을 나타내면 `/rewind`를 실행하여 해당 내용을 추가한 턴 이전의 체크포인트로 되돌아가거나, `/clear`를 실행하여 해당 내용이 포함되지 않은 대화를 시작합니다. * 프록시 또는 게이트웨이 뒤에서 Claude Code를 실행하는 경우 해당 프록시나 게이트웨이를 운영하는 담당자에게 오류를 보고합니다.

사용 정책 거부

대화의 내용이 [사용 정책](https://www.anthropic.com/legal/aup) 확인을 트리거했기 때문에 API가 응답을 거부했습니다. 메시지에 `` Details: `[reasoning_extraction]` `` 줄이 포함되어 있으면 [안전 조치가 Claude의 추론에 대한 요청을 플래그했습니다](#safeguards-flagged-a-request-for-claudes-reasoning)를 참조하십시오. 메시지에는 거부가 잘못되었다고 생각되는 경우 지원팀에 제시할 수 있는 요청 ID 및 메시지 ID가 포함됩니다. ```text theme={null} API Error: Opus 4.6 can't help with this. Start a new session to continue. Send feedback with /feedback or learn more: https://www.anthropic.com/legal/aup ``` 메시지는 거부한 모델을 표시하며, 기록된 모델이 없으면 `Claude`를 표시합니다. 확인은 최신 프롬프트뿐 아니라 전체 대화를 평가하므로 같은 세션에서 새 메시지를 보내면 일반적으로 동일한 거부가 다시 트리거됩니다. 디스크의 트랜스크립트에 트리거한 내용이 여전히 포함되어 있으므로 종료한 후 `--continue` 또는 `--resume`으로 세션을 다시 열어도 마찬가지입니다. [Amazon Bedrock](/docs/ko/amazon-bedrock), [Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai) 및 [Microsoft Foundry](/docs/ko/microsoft-foundry)에서는 이 메시지가 모델의 안전 조치가 사이버 보안 주제로 플래그한 요청도 다룹니다. [안전 조치가 사이버 보안 주제를 플래그했습니다](#safety-measures-flagged-a-cybersecurity-topic)를 참조하십시오. 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`를 실행하여 거부를 트리거한 턴 이전의 체크포인트로 되돌아간 다음, 다르게 표현하거나 다른 접근 방식을 취합니다. [체크포인트](/docs/ko/checkpointing)를 참조하십시오. * 어떤 턴이 원인인지 식별할 수 없으면 `/clear`를 실행하여 같은 프로젝트에서 새 대화를 시작합니다. 이전 대화는 디스크에 보존되며 `/resume`에서 계속 사용할 수 있습니다. * 되감기를 사용할 수 없는 [비대화형 모드](/docs/ko/headless)(`-p`)에서는 `--continue` 없이 새 세션에서 다르게 표현한 프롬프트로 재시도합니다. 정책 확인은 모델에 따라 다르므로 `--model`로 다른 모델로 전환하면 경우에 따라 거부가 해결될 수도 있습니다.

안전 조치가 사이버 보안 주제를 플래그했습니다

모델의 안전 조치가 대화의 내용을 사이버 보안 주제로 플래그했습니다. 메시지는 요청을 플래그한 모델을 표시합니다: ```text theme={null} API Error: Opus 4.8's safeguards flagged this message. Our intentionally broad safeguards allow us to deliver more capabilities faster, but can sometimes flag legitimate cybersecurity work. Apply to the Cyber Verification Program to reduce these interruptions. Send feedback with /feedback or learn more: https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude ``` 메시지에 `` Details: `[reasoning_extraction]` `` 줄이 포함되어 있으면 [안전 조치가 Claude의 추론에 대한 요청을 플래그했습니다](#safeguards-flagged-a-request-for-claudes-reasoning)를 참조하십시오. 메시지는 정당한 사이버 보안 작업에 대한 액세스를 부여하는 [사이버 검증 프로그램](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)으로 연결됩니다. Opus 5.5 및 Sonnet 5.5에서는 메시지가 대신 `'s safeguards flagged this session`으로 시작합니다. 플래그된 범주에 사용 가능한 대체 모델이 있으면 Claude Code는 이 오류를 표시하는 대신 [모델을 전환합니다](/docs/ko/model-config#automatic-model-fallback). [Amazon Bedrock](/docs/ko/amazon-bedrock), [Google Cloud의 Agent Platform](/docs/ko/google-vertex-ai) 및 [Microsoft Foundry](/docs/ko/microsoft-foundry)에서는 사이버 보안 플래그가 대신 [사용 정책 거부](#usage-policy-refusal) 메시지를 생성합니다. 안전 조치 자체는 서버 측에서 동작하며 v2.1.203 이전부터 존재했습니다. 그 이후의 클라이언트 릴리스는 메시지의 문구만 변경했습니다. v2.1.203부터 v2.1.218까지는 메시지가 ` 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 이전에는 `'s safeguards flagged this message for a cybersecurity topic. If your work requires this access, you can apply for an exemption:` 뒤에 면제 양식 링크가 붙는 형태였습니다. **할 일:** * 작업에 이 내용이 필요하면 [사이버 검증 프로그램](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)을 통해 액세스를 신청합니다. * 요청이 사이버 보안 주제와 관련이 없었다면 `/feedback`을 실행하여 오탐을 보고합니다. * 같은 세션에서 계속 작업하려면 Esc를 두 번 누르거나 `/rewind`를 실행하여 플래그를 트리거한 턴 이전의 체크포인트로 되돌아간 다음 다른 접근 방식을 취합니다. [체크포인트](/docs/ko/checkpointing)를 참조하십시오.

안전 조치가 Claude의 추론에 대한 요청을 플래그했습니다

안전 조치가 요청을 모델의 내부 추론을 응답에서 재현하도록 요구하는 것으로 플래그했기 때문에 API가 요청을 거부했습니다. API는 이 [거부 범주](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#refusal-response)를 `reasoning_extraction`이라고 부르며, 거부 메시지에는 다음 줄이 포함됩니다: ```text theme={null} Details: `[reasoning_extraction]` ``` v2.1.234 이전에는 거부 메시지에 `Details` 줄이 포함되지 않았습니다. **할 일:** * Claude에게 사고나 추론을 그대로 또는 고정된 형식으로 작성하도록 요구하는 지시를 제거하거나 다르게 표현합니다. 예를 들어 `` 섹션, 스크래치패드 섹션 또는 JSON 출력의 `reasoning` 필드 등이 있습니다. 이러한 지시는 프롬프트에 있을 수도 있고, CLAUDE.md, 스킬, 서브에이전트 프롬프트, 출력 스타일 또는 MCP 도구 설명처럼 Claude Code가 함께 로드하는 사용자 지정 항목에 있을 수도 있습니다. * 사용자 지정 항목이 원인인지 확인하려면 터미널에서 [`claude --safe-mode`](/docs/ko/cli-reference#cli-flags)를 실행하여 사용자 지정 항목이 비활성화된 세션을 시작한 다음 동일한 프롬프트를 보냅니다. * 사용자 지정 항목을 변경한 후에는 새 세션을 시작합니다. * 이미 보낸 프롬프트를 다르게 표현하려면 [되감기 및 요약](/docs/ko/checkpointing#rewind-and-summarize)을 참조하십시오. * Claude에게 답변을 설명하도록 요청하는 것은 여전히 가능합니다. 짧은 설명, 결과의 근거 또는 수행한 작업의 요약을 요청합니다. Claude의 사고 요약을 읽으려면 [`showThinkingSummaries`](/docs/ko/settings-reference#showthinkingsummaries)를 참조하십시오. * 더 많은 예시와 다르게 표현한 요청도 거부될 때의 조치는 [추론을 thinking 블록에 유지하기](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#keep-reasoning-in-thinking-blocks)를 참조하십시오.

Output blocked by content filtering policy

API의 출력 콘텐츠 필터가 Claude가 생성하던 응답을 중단했습니다. 메시지 텍스트는 API에서 제공됩니다: ```text theme={null} API Error: Output blocked by content filtering policy ``` Claude Code는 차단이 도착하는 즉시 오류를 표시하고 해당 요청을 종료합니다. 요청을 재시도하거나, 스트리밍 없이 다시 보내거나, [폴백 모델](/docs/ko/model-config#fallback-model-chains)로 전환하지 않습니다. v2.1.285 이전에는 Claude Code가 차단된 요청을 다시 보내고 재시도할 수 있었으며, 때로는 몇 분 동안 그렇게 한 후에야 오류를 표시했습니다. **할 일:** * 마지막 메시지를 다르게 표현하거나 다른 접근 방식을 취합니다. * 차단을 트리거한 턴 이전의 체크포인트로 되돌아가려면 Esc를 두 번 누르거나 `/rewind`를 실행합니다. [체크포인트](/docs/ko/checkpointing)를 참조하십시오.

설치 오류

이러한 오류는 Claude Code를 설치하거나 업데이트할 때 [설치 스크립트](/docs/ko/setup#install-claude-code), `claude install` 또는 `claude update`에서 나타납니다. 설정 중 `command not found`, PATH, 권한 및 TLS 문제의 경우 [설치 및 로그인 문제 해결](/docs/ko/troubleshoot-install)을 참조하십시오.

설치가 완료되기 전에 중단되었습니다

설치 스크립트는 `claude install` 단계가 신호에 의해 종료될 때 보고합니다. Linux에서 종료 코드 137은 프로세스가 SIGKILL을 수신했음을 의미하며, 메모리가 부족한 호스트에서는 일반적으로 커널 메모리 부족(OOM) 킬러입니다. 스크립트는 이 설명을 출력하고 코드 137로 종료됩니다: ```text theme={null} Installation was killed before it could finish (exit code 137). This usually means the system ran out of memory. Claude Code needs roughly 512MB of free memory to install. Free up memory, then run this script again. ``` 다른 치명적 신호의 경우, 그리고 macOS의 종료 코드 137의 경우, 스크립트는 `Installation was killed before it could finish (exit code )`을 출력하며 실제 종료 코드를 포함하고 메모리 부족 설명을 생략합니다. 메시지는 macOS 및 Linux가 사용하는 설치 스크립트에서 나오며, WSL 내부의 설치도 포함합니다. 네이티브 Windows 설치 스크립트는 절대 이를 출력하지 않습니다. v2.1.200 이전에는 스크립트가 셸의 단순한 `Killed` 줄로만 종료되었습니다. **수행할 작업:** * 다른 프로세스를 중지하여 메모리를 확보한 후 설치 프로그램을 다시 실행합니다 * 스왑 공간을 추가하거나 더 큰 인스턴스로 이동합니다. 스왑 파일 명령은 [메모리 부족 Linux 서버에서 설치 중단됨](/docs/ko/troubleshoot-install#install-killed-on-low-memory-linux-servers)을 참조하십시오.

업데이트를 다운로드하는 동안 연결이 끊어졌습니다

다운로드 서버로의 연결이 `claude install` 또는 `claude update`가 Claude Code 바이너리를 가져오는 동안 끊어졌으며, 재시도로 복구되지 않았습니다. Claude Code는 연결이 끊어지거나, 전송이 중단되거나, 다운로드된 파일이 체크섬에 실패할 때 다운로드를 재시도하며, 총 3번까지 시도합니다. 404와 같은 완료된 HTTP 오류는 서버가 이미 응답했기 때문에 재시도되지 않습니다. v2.1.202 이전에는 단일 연결 끊김이 재시도 대신 단순한 오류 `aborted`로 다운로드를 즉시 실패했습니다. ```text theme={null} The connection dropped while downloading the update (attempt 3/3: aborted). Check your network — proxies sometimes cut off large downloads. ``` 괄호의 텍스트는 어느 시도가 실패했는지와 기본 네트워크 오류를 나타냅니다. `claude update`는 stderr에서 메시지 앞에 `Error: Failed to install native update`를 붙입니다. 연결된 상태이지만 10분 이내에 완료되지 않는 다운로드는 `Download timed out: exceeded the total deadline` 메시지로 실패합니다. Claude Code는 시간 초과된 다운로드를 재시도하지 않습니다. 왜냐하면 기한 내에 완료할 수 없을 정도로 느린 연결은 즉시 재시도에서도 완료되지 않기 때문입니다. 아래 단계는 두 메시지 모두에 적용됩니다. 프록시 또는 게이트웨이는 완료되기 전에 긴 전송을 닫을 수 있으며, Claude Code 바이너리는 큰 다운로드입니다. **수행할 작업:** * `claude update`를 다시 실행합니다. 정상적인 네트워크에서는 다운로드가 일반적으로 다음 실행에서 성공합니다. 시간 초과 메시지의 경우 더 빠르거나 제한이 적은 네트워크에서 다시 실행합니다. * 네트워크에 프록시가 필요한 경우 설치 프로그램 또는 `claude update`를 실행하기 전에 `HTTPS_PROXY`를 설정합니다. [네트워크 연결 확인](/docs/ko/troubleshoot-install#check-network-connectivity)을 참조하십시오. * 회사 프록시가 계속 전송을 닫는 경우 네트워크 팀에 `downloads.claude.ai`에서 전체 다운로드를 허용하도록 요청합니다. [네트워크 액세스 요구 사항](/docs/ko/network-config#network-access-requirements)을 참조하십시오. * 설치 진단을 위해 셸에서 `claude doctor`를 실행합니다

명령줄 오류

이러한 오류는 `claude` 명령줄과 그 하위 명령, 프롬프트에 제출한 명령 이름, 그리고 `/security-review`처럼 프롬프트가 실행되기 전에 셸 명령을 실행하여 컨텍스트를 수집하는 명령에서 발생합니다. CLI를 다시 시작하는 `/tui`에서도 발생합니다.

`--bg`와 `--print` 간의 충돌

이 메시지는 Claude Code v2.1.198 이상이 필요합니다. 같은 `claude` 호출에서 `--bg`를 `-p` 또는 `--print`와 함께 사용했습니다. `--bg`는 나중에 `claude agents`로 연결하는 [백그라운드 세션](/docs/ko/agent-view#from-your-shell)을 시작하는 반면, `--print`는 [비대화형으로](/docs/ko/headless) 실행되며 `claude agents`가 연결하는 대화형 세션을 시작하지 않습니다. v2.1.198 이전에는 이 조합이 아무런 알림 없이 연결할 수 없는 백그라운드 작업을 생성했습니다. ```text theme={null} --bg and --print conflict: --print never starts the interactive session that `claude agents` attaches to, so the job would be unattachable. The prompt is the positional — drop --print: `claude --bg ''`. ``` **해결 방법:** * `-p` 또는 `--print`를 제거합니다. `--bg`는 프롬프트를 위치 인수로 받으므로 `claude --bg ""`만으로 완전한 명령이 됩니다. [셸에서 새 에이전트 Dispatch하기](/docs/ko/agent-view#from-your-shell)를 참조하십시오. * 백그라운드 세션을 만드는 대신 프롬프트를 비대화형으로 실행하고 결과를 출력하려면 `--bg`를 제거하고 `claude -p ""`를 실행합니다

시스템 프롬프트 플래그와 파일 형식 간의 충돌

하나의 `claude` 호출에서 [`--append-subagent-system-prompt`](/docs/ko/cli-reference#cli-flags)와 `--append-subagent-system-prompt-file`을 함께 전달했기 때문에 `claude`가 세션을 시작하지 않고 종료 코드 1로 종료됩니다: ```text theme={null} Error: Cannot use both --append-subagent-system-prompt and --append-subagent-system-prompt-file. Please use only one. ``` v2.1.283 이전에는 `--system-prompt`와 `--system-prompt-file`, 또는 `--append-system-prompt`와 `--append-system-prompt-file`을 함께 전달했을 때도 `claude`가 같은 방식으로 종료되었습니다. 이러한 쌍이 [결합](/docs/ko/cli-reference#system-prompt-flags)되지 않고 충돌했기 때문입니다. 해당 버전에서는 메시지에 함께 사용한 쌍이 표시됩니다. **해결 방법:** * 플래그의 한 가지 형식만 유지하고 다른 하나는 제거합니다. 고정된 프롬프트 파일과 실행별 텍스트를 결합하려면 두 플래그를 모두 전달하는 대신 실행 전에 텍스트를 파일에 병합합니다

잘못된 `--agents` 구성

`--agents`에 전달한 값이 잘못되어 `claude`가 세션을 시작하지 않고 종료 코드 1로 종료됩니다. `--safe-mode`를 전달하거나 [`CLAUDE_CODE_SAFE_MODE`](/docs/ko/env-vars#variables)를 설정하면 Claude Code는 `--agents`를 완전히 무시합니다. `--resume` 또는 `--continue`를 사용하면 인라인 JSON 값은 검사되지 않고 세션이 시작되지만, 파일에서 읽은 값은 매번 실행할 때마다 검사됩니다. v2.1.242 이전에는 Claude Code가 그래도 세션을 시작했습니다. ```text theme={null} Error: Invalid --agents configuration: ``` 첫 번째 줄 다음에 오는 내용은 값이 실패한 방식에 따라 달라집니다. Claude Code는 다음 검사를 순서대로 실행하고 처음 실패한 검사에서 멈춥니다. 값에 두 종류의 문제가 있으면 첫 번째 문제를 수정한 후에야 두 번째 문제가 표시됩니다: 1. 값이 `{`로 시작하지만 JSON으로 파싱되지 않거나 `--agents` 파일의 내용이 파싱되지 않으면, Claude Code는 JSON 파서 자체의 메시지를 담은 `invalid JSON:` 줄 하나를 출력합니다 2. 파싱은 되지만 에이전트 정의가 [CLI로 정의한 서브에이전트](/docs/ko/sub-agents#choose-the-subagent-scope)의 스키마와 일치하지 않으면, Claude Code는 문제마다 한 줄씩 출력합니다 3. 에이전트 이름이 `-`로 시작하면 Claude Code는 `: agent names must not start with '-'`를 출력합니다 문제 줄이 20개를 넘으면 Claude Code는 처음 20개를 출력하고 나머지는 `…and N more`로 대체합니다. `--print`와 함께 사용하면 `--agents`는 인라인 객체 대신 [JSON 파일 경로](/docs/ko/sub-agents#choose-the-subagent-scope)도 받습니다. 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: `**: 해당 경로에 파일이 없습니다. `{`로 시작하지 않고 유효한 JSON이 아닌 값은 경로로 읽히므로, 셸이 망가뜨린 인라인 JSON도 이런 방식으로 실패할 수 있습니다. 경로나 따옴표 처리를 확인하고 명령을 다시 실행합니다. **해결 방법:** * 메시지에 나열된 각 문제를 수정한 다음 명령을 다시 실행합니다. [CLI로 정의한 서브에이전트가 받는 필드](/docs/ko/sub-agents#choose-the-subagent-scope)를 참조하십시오.

`--restricted` 세션에서는 클라우드 세션을 만들 수 없음

[`--restricted`](/docs/ko/cli-reference#cli-flags)로 세션을 시작하면 Claude Code는 해당 세션에서 [클라우드 세션](/docs/ko/claude-code-on-the-web#from-terminal-to-cloud)을 만드는 것을 거부합니다. 새 세션은 제한된 프로세스 외부에서 실행되어 제한 모드를 적용하지 않기 때문입니다. Claude Code는 서버에 연결하기 전에 클라이언트에서 거부하므로 클라우드 세션이 생성되지 않습니다: ```text theme={null} Cloud sessions cannot be created from a --restricted session: they would not enforce it. ``` **해결 방법:** * 제한된 세션에서 작업을 로컬로 실행합니다 * 세션 실행 방식을 제어할 수 있다면 `--restricted` 없이 새 `claude` 세션을 시작하고 그곳에서 클라우드 세션을 만듭니다 v2.1.248 이전의 Claude Code에는 `--restricted` 플래그가 없었으며, 이전 버전은 알 수 없는 옵션 오류로 플래그 자체를 거부합니다.

조직 정책에 의해 클라우드 세션이 비활성화됨

조직의 `allow_remote_sessions` 정책이 꺼져 있어 [클라우드 세션](/docs/ko/claude-code-on-the-web)과 이를 사용하는 명령을 사용할 수 없습니다: ```text theme={null} Cloud sessions are disabled by your organization's policy. Contact your organization admin to enable them. ``` 이 메시지는 [터미널에서 클라우드 세션을 만들 때](/docs/ko/claude-code-on-the-web#from-terminal-to-cloud)와 `/teleport`, `/remote-env`, `/web-setup`처럼 클라우드 세션이 필요한 명령을 제출할 때 표시됩니다. v2.1.268 이전에는 이러한 명령을 제출하면 대신 [`Unknown command`](#unknown-command)가 반환되었습니다. 이는 서버 측 조직 정책이므로 로컬 설정, 환경 변수 또는 CLI 플래그로 재정의할 수 없습니다. Claude Code가 아직 조직 정책을 로드하지 않았거나 가져올 수 없는 경우, 해당 명령은 대신 `Couldn't verify your organization's policy for cloud sessions. Check your network connection, then restart Claude Code and try again.`로 응답합니다. **해결 방법:** * 조직의 [Owner](/docs/ko/server-managed-settings#access-control)에게 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)의 Claude Code 관리자 설정에서 클라우드 세션을 활성화하도록 요청합니다 * 메시지에 정책을 확인할 수 없다고 표시되면 네트워크 연결을 확인한 다음 Claude Code를 다시 시작하고 다시 시도합니다

`--json-schema` 값이 유효한 JSON Schema가 아님

[비대화형 모드](/docs/ko/headless#get-structured-output)에서 [`--json-schema`](/docs/ko/cli-reference#cli-flags)에 전달한 스키마가 JSON Schema 컴파일에 실패하여 `claude`가 프롬프트를 실행하지 않고 종료 코드 1로 종료됩니다. v2.1.205 이전에는 잘못된 스키마가 오류 없이 구조화되지 않은 출력을 생성했으며, `format` 키워드를 사용하는 스키마는 모두 잘못된 것으로 처리되었습니다. ```text theme={null} Error: --json-schema is not a valid JSON Schema: data/type must be equal to one of the allowed values ``` 두 번째 콜론 뒤의 텍스트는 검증기의 진단 내용이며 실패한 키워드나 위치를 알려 줍니다. `"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`로 거부합니다. **해결 방법:** * 진단 내용이 가리키는 스키마 부분을 수정한 다음 명령을 다시 실행합니다 * 작동하는 스키마와 명령은 [구조화된 출력 얻기](/docs/ko/headless#get-structured-output)를 참조하십시오

설정 파일이 2MiB 제한을 초과함

[`--settings`](/docs/ko/cli-reference#cli-flags)에 전달한 파일이 2MiB보다 커서 `claude`가 파일을 로드하지 않고 시작 시 종료 코드 1로 종료됩니다. v2.1.214 이전에는 Claude Code가 크기 검사 없이 파일을 읽었기 때문에, 수 기가바이트 크기의 파일이나 `/dev/zero` 같은 장치 파일로 인해 메모리가 무한히 증가했습니다. ```text theme={null} Error: Settings file exceeds the 2MiB limit: /path/to/settings.json ``` Claude Code는 일반 파일이 아닌 `--settings` 경로도 같은 방식으로 거부합니다. 장치, FIFO 또는 소켓의 경우 `Error: Cannot use settings file (Not a regular file (device, FIFO, or socket))` 뒤에 경로가 표시되고, 디렉터리의 경우 `EISDIR` 사유가 표시됩니다. **해결 방법:** * `--settings`가 2MiB 미만의 일반 JSON 설정 파일을 가리키도록 합니다. 형식은 [설정](/docs/ko/settings)을 참조하십시오.

현재 디렉터리가 더 이상 존재하지 않음

셸이 진입한 후 삭제되거나 이동된 디렉터리(예: 다른 셸이 제거한 worktree 또는 임시 디렉터리)에서 `claude`를 시작했습니다. Claude Code는 작업 디렉터리를 읽을 수 없으므로 대화형 모드와 [비대화형](/docs/ko/headless) 모드 모두에서 세션을 시작하기 전에 종료 코드 1로 종료됩니다. v2.1.239 이전에는 이 메시지 대신 Claude Code가 축소된 번들 소스와 원시 `ENOENT ... uv_cwd` 스택을 stderr에 출력하며 충돌했습니다. ```text theme={null} The current directory no longer exists (it was deleted or moved). Start Claude Code from an existing directory. error: The current working directory was deleted, so that command didn't work. Please cd into a different directory and try again. ``` 두 형식 모두 원인과 해결 방법이 같습니다. 권한 변경 등 다른 이유로 Claude Code가 작업 디렉터리를 읽을 수 없는 경우, 메시지에는 대신 오류 코드가 표시됩니다: `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`](/docs/ko/env-vars) 재정의 경로 아래에 비공개 임시 디렉터리 `claude-`를 만듭니다. 디렉터리를 만들 수 없거나 해당 경로에 이미 있는 항목이 안전 검사를 통과하지 못하면, Claude Code는 세션을 시작하지 않고 실패 내용을 stderr에 출력한 후 종료 코드 1로 종료됩니다: ```text wrap theme={null} ENOSPC: no space left on device, mkdir '/tmp/claude-501' Temp directory /tmp/claude-501 is not a directory (may be an attacker-planted symlink). Refusing to use it. Set CLAUDE_CODE_TMPDIR to a directory you control, or ask an administrator to remove it. Temp directory /tmp/claude-501 is owned by uid 502, expected 501. Refusing to use it — another user may have pre-created it. Set CLAUDE_CODE_TMPDIR to a directory you control, or ask an administrator to remove it. Temp directory /tmp/claude-501 is not readable (its mode may have been altered, or a path component denies search). Refusing to use it — restore its permissions (chmod 0700) or remove it. Set CLAUDE_CODE_TMPDIR to a directory you control, or ask an administrator to remove it. ``` **해결 방법:** * `ENOSPC`의 경우 임시 디렉터리가 있는 볼륨의 디스크 공간을 확보합니다 * `Refusing to use it` 형식의 경우 링크가 가리키는 대상이 아니라 메시지에 표시된 항목 자체를 제거하고 Claude Code를 다시 시작합니다. `owned by uid` 형식의 경우 관리자나 해당 사용자만 제거할 수 있습니다 * `is not readable`의 경우 표시된 디렉터리에 `chmod 0700`을 실행하거나, 디렉터리를 제거하고 다시 시작합니다 * 어떤 경우든 거부된 경로는 그대로 두고 [`CLAUDE_CODE_TMPDIR`](/docs/ko/env-vars)를 직접 제어하는 디렉터리로 설정한 다음 Claude Code를 다시 시작할 수 있습니다

디렉터리를 실제 위치로 확인할 수 없음

작업 디렉터리의 하위 디렉터리에 대해 `/add-dir`을 실행했지만 Claude Code가 해당 디렉터리의 실제 위치를 확인할 수 없었습니다. 작업 디렉터리의 하위 디렉터리에는 이미 파일 접근 권한이 있으므로 `/add-dir`은 해당 디렉터리의 스킬, 명령, 에이전트만 로드합니다. 이를 로드하기 전에 Claude Code는 심볼릭 링크를 모두 확인한 디렉터리의 실제 위치가 작업 디렉터리 내부에 있는지 검사합니다. Claude Code가 그 위치를 확인할 수 없으면 아무것도 로드하지 않고 다음 메시지를 표시합니다: ```text theme={null} packages/app couldn't be resolved to a real location, so its skills, commands, and agents weren't loaded. Check that it is a directory inside the working directory and try again. ``` **해결 방법:** * 경로가 작업 디렉터리 내부의 실제 디렉터리를 가리키는지 확인한 다음 `/add-dir`을 다시 실행합니다 * 이 메시지는 파일 접근 권한을 변경하지 않으며, 디렉터리의 `.claude/` 콘텐츠가 로드되지 않았음을 알릴 뿐입니다 v2.1.261 이전에는 작업 디렉터리가 `/net/` 자동 마운트에 있을 때 모든 `/add-dir `에 대해 이 메시지가 표시되었습니다. Claude Code는 설계상 그러한 위치의 경로를 확인하지 않으므로, 디렉터리에 문제가 없었고 재시도해도 소용이 없었습니다.

Remote Control 시작 시 워크스페이스를 신뢰하지 않음

신뢰하지 않은 디렉터리에서 `claude remote-control` 또는 그 별칭인 `claude rc`로 [Remote Control](/docs/ko/remote-control) 서버 모드를 시작했지만, 명령이 디렉터리를 신뢰할지 물을 수 없었습니다. 예를 들어 표준 입력이나 표준 출력 중 하나가 리디렉션되거나 파이프로 연결되어 터미널이 아닌 경우입니다. 명령은 종료 코드 1로 종료됩니다: ```text theme={null} Error: Workspace not trusted. Please run `claude` in /Users/you/project first to review and accept the workspace trust dialog. ``` `Error: Workspace not trusted.`로 시작하는 두 가지 변형은 디렉터리를 신뢰하면 켜지는 항목을 표시하기에 너무 작은 터미널이나 크기를 보고하지 않는 터미널에서도 나타납니다. 창을 키우거나 일반 터미널 창으로 전환한 다음 `claude rc`를 다시 실행합니다. 홈 디렉터리에서는 메시지가 다릅니다. 워크스페이스 신뢰 대화 상자는 홈 디렉터리에 대한 신뢰를 절대 저장하지 않으므로, 그곳에서 신뢰를 수락해도 이 검사를 통과할 수 없기 때문입니다. v2.1.214 이전에는 홈 디렉터리에서 위의 메시지가 표시되었으며, 그 조언은 홈 디렉터리에서 성공할 수 없었습니다. ```text theme={null} Error: Workspace not trusted. /Users/you is your home directory, and for security home-directory trust is never saved, so running `claude` here first won't help. Run `claude rc` from a project directory instead (run `claude` there once to accept the trust dialog). ``` [`Trust ?` 질문](/docs/ko/remote-control#requirements)에 `n`으로 답하거나 Enter를 누르면, 명령은 디렉터리 이름이 포함된 `Remote Control did not start` 메시지를 출력하고 종료 코드 1로 종료됩니다. `claude rc`를 다시 실행하여 `y`로 답합니다. **해결 방법:** * 먼저 터미널에서 디렉터리를 신뢰합니다. 그곳에서 `claude rc`를 실행하고 `y`로 답하거나, `claude`를 실행하고 [워크스페이스 신뢰 대화 상자](/docs/ko/permissions#project-allow-rules-and-workspace-trust)를 수락한 다음 원래 명령을 다시 실행합니다 * 홈 디렉터리에 있다면 프로젝트 디렉터리로 이동하여 그곳에서 Remote Control을 시작합니다 v2.1.284 이전에는 터미널에서도 명령이 묻지 않았습니다.

Remote Control이 시작하는 세션으로 전달되지 않음

`remote-control` 동사 앞에 전역 `claude` 플래그를 붙여 [Remote Control](/docs/ko/remote-control)을 시작했는데, 그 플래그가 `--settings`, `--setting-sources`, `--permission-mode`, `--disallowed-tools`, `--mcp-config`처럼 Remote Control이 시작하는 세션을 제한하거나 구성하는 플래그였습니다. 동사 앞에 놓인 플래그는 해당 세션에 전달되지 않습니다. Claude Code는 대신 플래그 이름을 표시하며 시작을 거부합니다: ```text theme={null} Error: `--settings` before `remote-control` is not carried over to the sessions Remote Control starts, so Remote Control refuses to start rather than drop it — remove it, and give Remote Control's own options after the verb (see `claude remote-control --help`). ``` `--verbose`, `--model`, 또는 래퍼가 주입한 `--session-id`나 `--plugin-dir`처럼 제외해도 무해한 전역 플래그는 거부하지 않습니다. Claude Code는 이를 무시하고 Remote Control을 시작합니다. Claude Code는 아직 무해한 것으로 인식하지 못한 전역 플래그에 대해서도 시작을 거부하므로, 새 릴리스에서 추가된 플래그가 이후 릴리스에서 무해한 것으로 표시될 때까지 이 메시지에 나타날 수 있습니다. **해결 방법:** * 동사 앞에서 플래그를 제거하고 [Remote Control 자체 옵션](/docs/ko/remote-control#start-a-remote-control-session)을 동사 뒤에 전달합니다. `claude remote-control --help`로 옵션 목록을 확인할 수 있습니다 * 거부된 플래그가 `--permission-mode`인 경우 `claude remote-control --permission-mode `를 실행하여 Remote Control이 시작하는 세션의 권한 모드를 설정합니다 v2.1.248 이전에는 전역 플래그가 먼저 오면 `claude remote-control`이 자체 플래그를 받지 않았으며, 명령이 `unknown option` 오류로 실패했습니다.

이 빌드에서는 아직 claude import를 사용할 수 없음

[`claude import`](/docs/ko/cli-reference#cli-commands)를 실행했지만 Claude Code가 가져오기 흐름이 꺼져 있음을 확인했으므로, 명령이 가져오기를 시작하지 않고 종료 코드 1로 종료됩니다. v2.1.222 이전에는 가져오기 흐름이 꺼진 빌드에서 `import`를 프롬프트로 처리하여 이 메시지를 출력하는 대신 대화형 세션을 시작했습니다. ```text theme={null} `claude import` is not yet available in this build. Run `claude` and use /mcp or edit ~/.claude/settings.json directly. ``` Claude Code는 Anthropic에서 가져와 디스크에 캐시하는 기능 플래그를 통해 `claude import`를 켭니다. 이 메시지는 캐시된 값이 꺼져 있음을 의미합니다. 원인은 대개 다음 중 하나입니다: * 설치 후 아직 세션을 시작하지 않아 Claude Code가 플래그를 가져오지 못했습니다. 기능을 사용할 수 있는 경우에도 첫 번째 `claude import`에서 이 메시지가 출력될 수 있습니다. * Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, Claude Platform on AWS 또는 [Claude apps 게이트웨이](/docs/ko/claude-apps-gateway#availability-and-limitations)를 통해 Claude Code를 사용합니다. 이러한 세션에서는 Claude Code가 기능 플래그를 가져오지 않으므로 `claude import`를 계속 사용할 수 없습니다. * 기능 플래그 가져오기를 끄는 `DISABLE_TELEMETRY`, `DO_NOT_TRACK`, `DISABLE_GROWTHBOOK` 또는 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](/docs/ko/env-vars)를 설정했으므로 `claude import`를 계속 사용할 수 없습니다. **해결 방법:** * 새로 설치한 경우 `claude`를 시작하고 세션이 로드될 때까지 기다린 다음 종료하고 `claude import`를 다시 실행합니다 * 기능 플래그 가져오기가 계속 꺼져 있는 환경에서는 구성을 직접 설정합니다. [`claude mcp add`](/docs/ko/mcp#installing-mcp-servers)로 MCP 서버를 추가하고, 옮기려는 [`CLAUDE.md` 파일](/docs/ko/memory#how-claude-md-files-load), [스킬과 명령](/docs/ko/skills#where-skills-live), [서브에이전트](/docs/ko/sub-agents#choose-the-subagent-scope)를 만듭니다. 메시지에는 `~/.claude/settings.json`도 언급됩니다. `claude import`가 옮기는 구성 중 해당 파일에는 [권한 모드](/docs/ko/settings-reference#permission-settings)만 들어 있으며, Claude Code는 이 파일에서 MCP 서버를 읽지 않습니다.

Claude Code 구성을 읽을 수 없음

Claude Code가 로그인 정보와 프로젝트별 상태를 저장하는 파일인 `~/.claude.json`을 파싱할 수 없는 상태에서 [`claude import`](/docs/ko/cli-reference#cli-commands)를 실행했습니다. 이 하위 명령은 사용 가능 여부를 확인하기 위해 해당 파일을 읽지만 대화형 세션이 표시하는 복구 대화 상자를 표시하지 않으므로 종료 코드 1로 종료됩니다. v2.1.222 이전에는 설정 파일을 읽을 수 없을 때 `claude import`가 대화형 세션을 시작했고, 그 세션의 복구 대화 상자가 파일을 처리했습니다. ```text theme={null} Could not read Claude Code config — run `claude` with no arguments to recover it. ``` **해결 방법:** * 인수 없이 `claude`를 실행합니다. Claude Code가 잘못된 파일을 감지하고 재설정을 제안합니다. 그런 다음 `claude import`를 다시 실행합니다. * 직접 수정한 내용을 유지하려면 대신 편집기에서 `~/.claude.json`의 JSON 구문을 수정한 다음 `claude import`를 다시 실행합니다

Claude Desktop에서 서버를 가져올 수 없음

Claude Code가 `claude mcp add-from-claude-desktop`에서 선택한 서버 중 하나를 추가할 수 없었습니다. 명령은 선택한 다른 서버는 계속 가져오며, 추가할 수 없었던 서버마다 한 줄씩 출력합니다. v2.1.205 이전에는 처음 실패한 서버에서 가져오기가 중단되었습니다. ```text theme={null} Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores. ``` 서버 이름 뒤의 텍스트가 사유입니다. 가장 흔한 사유는 이름 검사입니다. Claude Desktop은 서버 이름에 공백이나 마침표 같은 문자를 허용하지만, `claude mcp`는 문자, 숫자, 하이픈, 밑줄로 제한합니다. 그 밖의 사유로는 검증에 실패한 서버 구성과 조직의 [MCP 정책](/docs/ko/managed-mcp)에 의해 차단된 서버가 있습니다. **해결 방법:** * `claude_desktop_config.json`에서 서버 이름을 문자, 숫자, 하이픈, 밑줄만 사용하도록 변경한 다음 `claude mcp add-from-claude-desktop`을 다시 실행합니다 * 유효한 이름으로 `claude mcp add` 또는 `claude mcp add-json`을 사용해 해당 서버를 직접 추가합니다. [Claude Desktop에서 MCP 서버 가져오기](/docs/ko/mcp#import-mcp-servers-from-claude-desktop)를 참조하십시오.

managed 범위에 MCP 서버를 추가할 수 없음

`--scope managed`와 함께 `claude mcp add` 또는 `claude mcp add-json`을 실행했습니다. 이 범위에는 조직이 [`managedMcpServers`](/docs/ko/settings-reference#managedmcpservers) 관리형 설정을 통해 제공하는 서버가 들어 있습니다. Claude Code는 관리형 설정에서만 이를 읽으므로 명령이 해당 범위에 서버를 쓸 수 없습니다. ```text theme={null} Cannot add MCP server to scope: managed ``` **해결 방법:** * 쓸 수 있는 범위(`local`, `user` 또는 `project`)에 서버를 추가합니다. `--scope`가 없으면 명령은 `local`을 사용합니다. [MCP 설치 범위](/docs/ko/mcp#mcp-installation-scopes)를 참조하십시오 * 조직의 모든 사용자에게 서버를 제공하려면 배포하는 관리형 설정의 [`managedMcpServers`](/docs/ko/settings-reference#managedmcpservers)에 추가합니다

관리형 설정이 플러그인 서버만 허용할 때 MCP 서버를 추가할 수 없음

조직의 관리형 설정이 [`strictPluginOnlyCustomization`](/docs/ko/settings-reference#strictpluginonlycustomization)을 `true` 또는 `mcp`가 포함된 목록으로 설정한 상태에서 `claude mcp add` 또는 `claude mcp add-json`을 실행했습니다. 이 설정이 있으면 Claude Code는 `~/.claude.json`이나 `.mcp.json`에서 MCP 서버를 로드하지 않으므로, 명령은 절대 로드되지 않을 서버를 저장하는 대신 종료 코드 1로 종료됩니다: ```text theme={null} Cannot add MCP server: your organization's managed settings allow only MCP servers that plugins provide. Install a plugin that provides this server, or ask your administrator to make it available. ``` `claude mcp add-from-claude-desktop`은 선택한 각 서버를 가져오지 않은 것으로 보고하며, 이 메시지를 사유로 표시합니다. [`/import`](/docs/ko/commands#all-commands)는 추가하려는 각 MCP 서버에 대해 이 메시지를 보고하고, 찾은 다른 항목은 계속 가져옵니다. v2.1.284 이전에는 이러한 명령이 서버를 저장하고 성공을 보고했지만 서버는 로드되지 않았습니다. **해결 방법:** * 해당 서버를 제공하는 [플러그인](/docs/ko/plugins/install)을 설치합니다 * 관리자에게 서버를 [플러그인](/docs/ko/plugins/org)으로 배포하거나, 원격 HTTP 또는 SSE 서버인 경우 [`managedMcpServers`](/docs/ko/settings-reference#managedmcpservers)를 통해 제공하도록 요청합니다

.mcp.json을 읽을 수 없음

`--scope project`와 함께 실행한 `claude mcp add` 또는 `claude mcp add-json`, 또는 `claude mcp remove`처럼 프로젝트의 [`.mcp.json`](/docs/ko/mcp#project-scope)을 읽는 명령이 현재 디렉터리의 파일이 일반 파일이 아니거나 2MiB보다 크다는 것을 발견했기 때문에, 파일을 읽지 않고 이 오류와 함께 종료됩니다. ```text theme={null} Can't read .mcp.json: it isn't a regular file or is larger than 2097152 bytes. Fix or remove it, then run the command again. ``` v2.1.257 이전에는 `.mcp.json` 위치에 FIFO가 있으면 명령이 출력 없이 무한히 대기했고, `/dev/zero` 같은 장치 파일을 가리키는 심볼릭 링크가 있으면 프로세스가 종료될 때까지 메모리가 증가했습니다. **해결 방법:** * 현재 디렉터리의 `.mcp.json` 위치에 무엇이 있는지 확인합니다. [프로젝트 범위 형식](/docs/ko/mcp#project-scope)의 일반 JSON 파일로 교체하거나 삭제한 다음 명령을 다시 실행합니다.

MCP 서버가 저장되거나 제거되지 않음

`user` 또는 `local` [범위](/docs/ko/mcp#mcp-installation-scopes)의 서버에 대해 `claude mcp add`, `claude mcp add-json` 또는 `claude mcp remove`를 실행했습니다. 두 범위 모두 `~/.claude.json`에 저장되는데, 쓰기 후 Claude Code가 파일을 다시 읽었을 때 변경 사항이 파일에 없었습니다. 명령은 성공 메시지 대신 이 오류와 함께 종료됩니다. ```text theme={null} MCP server "example" was not saved to /home/user/.claude.json. If that file is read-only or protected by a sandbox, make it writable or run the command outside the sandbox, then add the server again. ``` 제거 후에는 메시지가 `was not removed from`으로 표시되고 `then remove the server again`으로 끝납니다. `local` 범위 서버의 경우 경로 뒤에 해당 항목이 속한 프로젝트 디렉터리가 `(local scope for /path/to/project)` 형식으로 표시됩니다. v2.1.283 이전에는 변경 사항이 파일에 반영되지 않은 경우에도 `claude mcp add`, `claude mcp add-json`, `claude mcp remove`가 성공을 보고했습니다. **해결 방법:** * 메시지에 표시된 파일을 쓰기 가능하게 만들거나 샌드박스 외부에서 명령을 실행한 다음, 같은 추가 또는 제거 명령을 다시 실행합니다.

MCP 서버가 저장되거나 제거되지 않았을 수 있음

`user` 또는 `local` [범위](/docs/ko/mcp#mcp-installation-scopes)의 서버에 대해 `claude mcp add`, `claude mcp add-json` 또는 `claude mcp remove`를 실행했지만, Claude Code가 변경 사항을 확인하기 위해 `~/.claude.json`을 다시 읽을 수 없었습니다. 변경 사항이 디스크에 반영되었을 수도 있고 그렇지 않을 수도 있습니다. 괄호 안의 텍스트는 해당 읽기에서 발생한 오류입니다. ```text theme={null} MCP server "example" may not have been saved: /home/user/.claude.json could not be read to confirm the change (EACCES: permission denied, open '/home/user/.claude.json'). Run `claude mcp get example` to check, then add the server again if it is missing. ``` 제거 후에는 메시지가 `may not have been removed`로 표시되고 `then remove the server again if it is still listed`로 끝납니다. v2.1.283 이전에는 변경 사항을 확인할 수 없는 경우에도 명령이 성공을 보고했습니다. **해결 방법:** * `claude mcp get `을 실행하여 변경 사항이 디스크에 있는지 확인합니다. `local` 범위 서버의 경우 로컬 범위는 프로젝트별이므로 서버가 속한 프로젝트 디렉터리에서 실행합니다. * 추가 후 서버가 없거나 제거 후에도 여전히 목록에 있으면 같은 추가 또는 제거 명령을 다시 실행합니다.

서버가 Anthropic에서 호스팅되며 로컬 OAuth를 지원하지 않음

URL이 타사 ID 공급자를 통해 인증하는 Anthropic 호스팅 커넥터 호스트를 가리키는 MCP 서버에 대해 로그인을 시작했습니다. 이러한 호스트에는 `microsoft365.mcp.claude.com`, `gmail.mcp.claude.com`, `gcal.mcp.claude.com`이 포함됩니다. [이들의 로그인은 claude.ai를 통해서만 작동](/docs/ko/mcp#use-mcp-servers-from-claude-ai)하므로, Claude Code는 `/mcp` 패널과 `claude mcp login` 모두에서 이러한 호스트에 대한 로컬 OAuth 흐름 시작을 거부합니다. ```text theme={null} "gmail" is Anthropic-hosted and doesn't support local OAuth. Connect it via Settings → Connectors on claude.ai (requires `claude login`), then it'll be available here automatically. ``` **해결 방법:** * 같은 URL의 claude.ai 커넥터를 가리지 않도록 `claude mcp remove `으로 항목을 제거합니다 * 제거한 후 Claude Code에서 사용하는 계정으로 로그인한 상태에서 [claude.ai/customize/connectors](https://claude.ai/customize/connectors)에서 서비스를 연결합니다. 연결되면 활성 인증 방법이 claude.ai 구독 로그인인 경우 [커넥터가 Claude Code에 자동으로 표시됩니다](/docs/ko/mcp#use-mcp-servers-from-claude-ai)

구성된 headersHelper가 생성한 Authorization 헤더를 서버가 거부함

[`headersHelper`](/docs/ko/mcp#use-dynamic-headers-for-custom-authentication)가 `Authorization` 헤더를 제공하는 MCP 서버가 연결에 HTTP 401 또는 403으로 응답했기 때문에 Claude Code가 연결을 실패로 보고합니다. 헬퍼가 `Authorization` 헤더를 제공하므로 Claude Code는 해당 서버에 대해 [OAuth로 폴백하지 않습니다](/docs/ko/mcp#authenticate-with-remote-mcp-servers): ```text theme={null} Server rejected the Authorization header minted by the configured headersHelper (HTTP 401). Check that the helper command returns a valid credential for this MCP endpoint — OAuth fallback is disabled when the helper supplies Authorization. ``` Claude Code는 연결을 시도할 때마다 헬퍼를 다시 실행하므로, 토큰 교체 경합처럼 일시적인 거부 이후의 재시도는 새 자격 증명으로 성공할 수 있습니다. **해결 방법:** * Claude Code가 실행하는 방식 그대로 `headersHelper` 명령을 직접 실행합니다. [Claude Code가 실행하는 디렉터리](/docs/ko/mcp#where-the-helper-runs)에서, [Claude Code가 설정하는 환경 변수](/docs/ko/mcp#use-dynamic-headers-for-custom-authentication)와 함께, 그리고 프로젝트 `.mcp.json`, 플러그인 또는 프로젝트 에이전트 파일의 서버인 경우 [Claude Code가 제거하는 자격 증명 변수](/docs/ko/mcp#which-variables-a-helper-can-read) 없이 실행합니다. 서버의 엔드포인트가 수락하는 `Authorization` 값이 출력되는지 확인합니다 * 헬퍼나 자격 증명 소스를 수정한 후 `/mcp`에서 서버를 선택하고 **Reconnect**를 선택합니다 v2.1.248 이전에는 헬퍼가 `Authorization` 헤더를 제공하는 서버에 대해서도 Claude Code가 OAuth 검색을 실행했습니다. 이 검색은 거부된 자격 증명을 보고하는 대신 `Incompatible auth server: does not support dynamic client registration`으로 실패할 수 있었습니다.

MCP 권한 프롬프트 도구를 찾을 수 없음

실행에서 처음으로 권한 결정이 필요했을 때 [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags)에 전달한 도구가 연결된 MCP 도구 중에 없었습니다. 해당 서버가 연결되지 않았거나, 연결된 서버 중 그 이름의 도구를 노출하는 서버가 없기 때문입니다. Claude Code는 여전히 프롬프트를 전송합니다. [비대화형](/docs/ko/headless) 실행은 첫 번째 도구 호출에서 이 오류와 종료 코드 1로 종료되므로, 요청은 이루어졌지만 응답은 생성되지 않습니다. 첫 번째 프롬프트 전에 Claude Code는 [`MCP_TIMEOUT`](/docs/ko/env-vars)으로 설정된 서버별 연결 타임아웃인 최대 30초 동안 해당 서버가 연결되기를 기다립니다. v2.1.206 이전에는 시작 시 서버 연결이 완료될 때까지 기다리지 않았기 때문에, 시작이 느리지만 정상인 서버에서도 이 오류가 발생했습니다. ```text theme={null} Error: MCP tool mcp__permissions__approve (passed via --permission-prompt-tool) not found. Available MCP tools: none ``` `Available MCP tools:` 뒤의 목록은 연결되어 있던 MCP 도구를 나타냅니다. **해결 방법:** * 서버가 시작되어 연결을 유지하는지 확인합니다. 같은 디렉터리에서 `claude mcp list`를 실행하고 서버가 연결된 상태로 표시되는지 확인합니다 * 도구 이름이 서버가 노출하는 `mcp____` 이름과 일치하는지 확인합니다 * 서버 시작에 30초 넘게 걸리면 [`MCP_TIMEOUT`](/docs/ko/env-vars)을 늘립니다

OAuth 콜백 포트가 이미 사용 중임

OAuth로 원격 MCP 서버에 로그인하면 Claude Code는 로그인 콜백을 받기 위해 로컬 리스너를 시작합니다. 리스너에 필요한 포트를 다른 프로세스가 점유하고 있으면 이 메시지와 함께 로그인이 실패합니다. 이는 주로 [`MCP_OAUTH_CALLBACK_PORT`](/docs/ko/env-vars) 변수나 `--callback-port`로 [고정 콜백 포트](/docs/ko/mcp#use-a-fixed-oauth-callback-port)를 설정한 경우에 발생합니다. 고정 포트가 없으면 Claude Code가 사용 가능한 포트를 선택하기 때문입니다. ```text theme={null} OAuth callback port is already in use — another process may be holding it. Run `lsof -ti: -sTCP:LISTEN` to find it. ``` Windows에서는 대신 `netstat -ano | findstr :` 명령이 제안됩니다. **해결 방법:** * 메시지의 명령을 실행하여 포트를 점유한 프로세스를 찾고, 해당 프로세스를 중지하거나 완료될 때까지 기다립니다 * 다른 프로그램이 해당 포트를 계속 사용해야 한다면 서버에 다른 리디렉션 URI를 등록하고, 사용하는 방식에 따라 `MCP_OAUTH_CALLBACK_PORT` 또는 `--callback-port`로 그 포트를 설정합니다 * 그런 다음 `/mcp`에서 서버를 선택하는 등의 방법으로 로그인을 다시 시작합니다

OAuth 리디렉션에 사용할 수 있는 포트가 없음

[OAuth](/docs/ko/mcp#authenticate-with-remote-mcp-servers)로 원격 MCP 서버에 로그인하면 Claude Code는 로그인 콜백을 받기 위해 로컬 리스너를 시작합니다. Claude Code가 이를 위한 로컬 포트를 바인딩할 수 없으면 이 메시지와 함께 로그인이 실패합니다. 보안 소프트웨어나 로컬 리스너를 거부하는 샌드박스 정책처럼 시스템의 무언가가 `127.0.0.1`에서의 수신을 막고 있습니다. ```text theme={null} No available ports for OAuth redirect ``` v2.1.268 이전에는 Claude Code가 운영 체제가 할당한 포트로 폴백하지 않았기 때문에, 자체적으로 선택한 포트만 바인딩할 수 없는 경우에도 이 메시지가 표시되었습니다. 이는 Hyper-V가 Claude Code가 선택하는 포트를 포함하는 포트 범위를 예약하는 Windows 호스트에서 발생할 수 있습니다. **해결 방법:** * 보안 소프트웨어나 샌드박스 정책이 프로세스의 `127.0.0.1` 수신을 차단하는지 확인하고, Claude Code가 로컬 포트를 바인딩하도록 허용합니다 * 그런 다음 `/mcp`에서 서버를 선택하는 등의 방법으로 로그인을 다시 시작합니다

origin/HEAD가 없으면 /security-review가 실패함

[`/security-review`](/docs/ko/commands#all-commands)는 브랜치를 `origin/HEAD`와 비교한 diff로 리뷰 컨텍스트를 구성합니다. `origin/HEAD`는 `origin` 원격의 기본 브랜치가 무엇인지 기록하는 로컬 ref입니다. 이 ref가 없으면 diff를 수집하는 git 명령이 실패하고 리뷰가 시작되기 전에 중단됩니다. ```text theme={null} Error: Shell command failed for pattern "!`git diff --name-only origin/HEAD...`": [stderr] fatal: ambiguous argument 'origin/HEAD...': unknown revision or path not in the working tree. Use '--' to separate paths from revisions, like this: 'git [...] -- [...]' ``` 메시지에 `git log`나 다른 `git diff`가 대신 표시될 수도 있습니다. Git은 원격이 기본 브랜치를 알리고 fetch refspec이 그 브랜치를 포함할 때만 `origin/HEAD`를 만듭니다. 커밋이 있는 원격을 전체 `git clone`하면 이 조건이 충족됩니다. 다음과 같은 환경에서는 ref가 없습니다: * 너무 좁은 refspec을 가져오는 단일 브랜치 또는 CI 체크아웃 * 서버 측 HEAD가 아무도 푸시하지 않은 브랜치를 가리키는 원격 * `origin` 원격이 없거나 한 번도 fetch하지 않은 저장소 Claude Code는 [동적 컨텍스트를 주입하는](/docs/ko/skills#when-an-injected-command-fails) 모든 스킬에 대해 같은 오류를 표시하며, 주입된 명령이 실패하면 해당 스킬 호출이 중단됩니다. 명령이 실행되기도 전에 발생하는 두 가지 유사한 문자열이 있습니다: * `Shell command permission check failed for pattern "..."`: 명령의 권한 검사에서 허용되지 않았습니다. [주입된 명령에 대한 권한 검사](/docs/ko/skills#permission-checks-on-injected-commands)에서 각 권한 모드에서 어떤 결과가 중단을 일으키는지, 그리고 `allowed-tools`로 명령을 사전 승인하는 방법을 다룹니다 * ``Skill requires bash (`shell: bash` in frontmatter) but Git Bash was not found``: 스킬의 frontmatter가 bash가 없는 시스템에서 bash를 요구합니다. Git for Windows를 설치하거나 frontmatter를 `shell: powershell`로 변경합니다. [주입된 명령이 실행되는 방식](/docs/ko/skills#how-injected-commands-run)을 참조하십시오 **해결 방법:** * 원격의 기본 브랜치 이름을 지정하여 ref를 만듭니다: `git remote set-head origin `. 이는 로컬 추적 ref `origin/`가 있으면 항상 작동합니다. 단일 브랜치 클론처럼 해당 ref가 없으면 먼저 브랜치를 fetch합니다. `git remote set-branches --add origin `를 실행하고, 이어서 `git fetch origin`을 실행한 다음, set-head 명령을 다시 실행합니다. 그런 다음 `/security-review`를 다시 실행합니다. * 브랜치 이름을 지정하고 싶지 않다면 `git fetch origin`을 실행한 다음 `git remote set-head origin --auto`를 실행합니다. 이 명령은 원격에 기본 브랜치가 무엇인지 묻습니다. 원격이 비어 있거나 HEAD가 아무도 푸시하지 않은 브랜치를 가리켜 기본 브랜치를 알리지 않으면 `error: Cannot determine remote HEAD`로 실패하므로, 대신 브랜치 이름을 명시적으로 지정합니다. 클론이 해당 브랜치를 fetch하지 않으면 `error: Not a valid ref`로 실패하므로, 먼저 위와 같이 refspec을 넓힙니다. * 저장소에 원격이 없으면 `git remote add origin `로 원격을 추가하고 ref를 만들기 전에 fetch합니다. 원격이 비어 있으면 먼저 `git push -u origin HEAD`로 브랜치를 푸시하고 set-head 명령에 해당 브랜치 이름을 지정합니다. 그러면 `origin/HEAD`가 방금 푸시한 브랜치를 가리키므로, 브랜치가 그로부터 갈라질 때까지 `/security-review`는 빈 diff를 보게 됩니다.

`--print` 사용 시 입력을 제공해야 함

인수 없는 `claude`는 대화형 UI를 시작하기 위해 stdout이 터미널이어야 합니다. stdout이 리디렉션되었거나, PowerShell ISE나 일부 IDE 출력 창처럼 콘솔이 실제 터미널이 아니면 `claude`는 대신 [비대화형으로](/docs/ko/headless) 실행됩니다. 이는 프롬프트가 필요한 `claude -p`와 같은 모드이므로, 플래그를 전달하지 않았더라도 메시지에 `--print`가 표시됩니다. 프롬프트 없이, stdin으로 파이프된 내용도 없이 `-p`/`--print`를 전달하면 어디서든 같은 오류가 발생합니다. ```text theme={null} Error: Input must be provided either through stdin or as a prompt argument when using --print ``` **해결 방법:** * 대화형으로 사용하려면 실제 터미널에서 `claude`를 실행합니다. ISE 대신 Windows Terminal이나 PowerShell 콘솔을, 출력 창 대신 IDE의 통합 터미널을 사용합니다 * 일회성으로 사용하려면 프롬프트를 전달합니다: `claude -p "your question"`, 또는 `echo "your question" | claude -p`로 파이프합니다

이 환경에서는 Claude Code가 키보드 입력을 읽을 수 없음

[`-p`](/docs/ko/headless) 없이 `claude`를 실행하여 [대화형 세션](/docs/ko/interactive-mode)을 시작했지만, 표준 입력이 터미널이 아닙니다. 무언가가 입력을 파이프하거나 리디렉션했거나, `claude`를 실행한 프로그램이 자체 입력 스트림을 제공했습니다. 대화형 세션은 키 입력을 읽을 터미널이 필요하며, 터미널이 없을 때 Claude Code의 동작은 플랫폼에 따라 다릅니다: * **Windows**: Claude Code는 인터페이스를 시작하지 않고 stderr에 메시지를 출력한 후 종료 코드 1로 종료됩니다 * **macOS 및 Linux**: Claude Code는 `/dev/tty`에서 키 입력을 읽어 세션을 시작하며, 파이프된 텍스트가 있으면 첫 번째 프롬프트로 사용합니다. `/dev/tty`를 열 수 없을 때 메시지가 표시되며, 첫 번째 줄에는 Windows 문구 대신 `/dev/tty`가 표시됩니다. Windows에서는 메시지가 다음과 같습니다: ```text theme={null} Claude Code can't read the keyboard here: stdin is not a terminal (it is piped, redirected, or supplied by the program that launched claude), and on Windows it can't fall back to the console for input yet. Run claude directly in Windows Terminal, PowerShell, or Command Prompt, without piping or redirecting its input. To send text as a prompt and print the reply instead, add -p; it also works with --continue and --resume (for example: type notes.md | claude -p --continue). ``` **해결 방법:** * 대화형으로 작업하려면 입력을 파이프하거나 리디렉션하지 않고 터미널에서 직접 `claude`를 실행합니다 * 스크립트에서처럼 대화형 인터페이스 없이 응답을 받으려면 `-p`를 추가하고 프롬프트를 인수나 stdin으로 전달합니다. 예: `claude -p "your question"` 또는 `echo "your question" | claude -p`. `--continue` 및 `--resume `와도 같은 방식으로 작동합니다. v2.1.287 이전에는 Claude Code가 이 메시지를 출력하는 대신 인터페이스를 시작했고, 화면에 아무것도 표시하지 않거나 `Raw mode is not supported`가 포함된 오류로 실패했습니다. 대신 `claude install` 중에 `Raw mode is not supported`가 표시되면 [설치 중 `Raw mode is not supported`](/docs/ko/troubleshoot-install#raw-mode-is-not-supported-during-install)를 참조하십시오.

입력에 공백만 포함됨

[비대화형 모드](/docs/ko/headless)에서 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](/docs/ko/agent-sdk/overview) 세션에 제출된 메시지**: Claude Code는 모델을 호출하지 않고 턴을 종료하며 세션은 계속 사용할 수 있습니다. 거부 내용은 정보 메시지와 턴의 결과 텍스트로 전달됩니다: `Blank prompt — the message was only whitespace, so nothing was sent to the model.` v2.1.229 이전에는 Claude Code가 공백만 있는 메시지를 API에 전송했고, API는 400 오류로 요청을 거부했습니다. **해결 방법:** * 프롬프트에 보이는 텍스트를 포함합니다. 스크립트가 변수나 파일에서 프롬프트를 만든다면 Claude Code를 호출하기 전에 소스가 비어 있지 않은지 확인합니다.

stream-json 입력이 줄 바꿈 없이 256M 문자를 초과함

프로그램이 `claude -p --input-format stream-json` 실행의 stdin에 줄 바꿈 없이 268,435,456자를 넘게 보냈기 때문에, Claude Code는 더 이상 입력을 버퍼링하지 않고 stderr에 이 오류를 출력한 후 종료 코드 1로 종료됩니다. 메시지는 이 한도를 `256M`으로 표시합니다. v2.1.257 이전에는 Claude Code가 이러한 입력을 제한 없이 버퍼링하여, 프로세스가 충돌하거나 종료될 때까지 메모리가 증가했습니다. ```text theme={null} Error: stream-json input carried over 256M characters with no newline. Each stream-json message must be a single newline-terminated JSON line: either the producer is not newline-terminating its messages, or one message exceeded this budget. ``` 줄 바꿈 없이 이렇게 긴 입력은 대개 생산자가 애초에 stream-json 생산자가 아님을 의미합니다. 예를 들어 바이너리 파일이나 일반 로그 출력이 실수로 파이프된 경우입니다. 한도를 초과하는 단일 메시지도 같은 검사에서 실패합니다. **해결 방법:** * stdin으로 무엇이 파이프되는지 확인합니다. [`--input-format stream-json`](/docs/ko/cli-reference#cli-flags)에서는 모든 메시지가 줄 바꿈으로 끝나는 JSON 한 줄이어야 합니다 * 대신 일반 텍스트를 보내려면 `--input-format stream-json`을 제거합니다. `claude -p`는 기본적으로 stdin에서 일반 텍스트 프롬프트를 읽습니다

Unknown command

대화형 터미널 세션에서 이 세션의 어떤 명령과도 일치하지 않는 `/` 이름을 제출했기 때문에, Claude Code는 아무것도 실행하지 않고 해당 이름을 보고합니다: ```text theme={null} Unknown command: /hepl. Did you mean /help? ``` Claude Code는 이 세션의 메뉴에 나열된 명령 이름이나 별칭 중 가장 가까운 것을 제안합니다. 가까운 것이 없으면 메시지는 이름 뒤에서 끝납니다. 원인은 대개 다음 중 하나입니다: * `/help`를 `/hepl`로 입력한 것 같은 오타. [명령 메뉴가 입력 내용과 일치시키는 방식](/docs/ko/commands#how-the-command-menu-matches-what-you-type)에서 제출 전에 가까운 항목을 선택하는 방법을 다룹니다 * 명령은 존재하지만 플랫폼, 플랜 또는 인증 방법 같은 요구 사항이 충족되지 않아 이 세션에서 사용할 수 없는 경우. [`/web-setup`](/docs/ko/web-quickstart#web-setup-shows-no-commands-match-or-unknown-command) 및 [`/schedule`](/docs/ko/routines#schedule-returns-unknown-command)의 문제 해결 항목에서 두 가지 일반적인 사례를 설명합니다. 일부 명령은 조직 정책에 의해 비활성화된 경우 [`Cloud sessions are disabled by your organization's policy`](#cloud-sessions-are-disabled-by-your-organizations-policy)처럼 자체 메시지로 응답합니다 * 이 세션에 설치되거나 연결되지 않은 [플러그인](/docs/ko/plugins/overview) 또는 [MCP 서버](/docs/ko/mcp#use-mcp-prompts-as-commands)의 명령 Claude Code는 대화형 터미널 세션에서만 일치하지 않는 `/` 이름에 이런 방식으로 응답합니다. 그 밖의 모든 세션에서는 프롬프트를 일반 메시지로 Claude에 보내며, 명령이 실행되지 않았다는 메모와 세션에서 Claude가 실행할 수 있는 명령 목록을 함께 보냅니다. 이러한 세션은 다음과 같습니다: * `-p` 실행 * [Agent SDK](/docs/ko/agent-sdk/overview) 애플리케이션 * [데스크톱 앱](/docs/ko/desktop)의 Code 탭 * [VS Code 확장](/docs/ko/vs-code)의 채팅 패널 * [클라우드 세션](/docs/ko/claude-code-on-the-web) 및 [루틴](/docs/ko/routines) 이러한 세션 중 하나에서 실행할 수 없는 기본 제공 명령의 경우, Claude Code는 여전히 명령을 Claude에 보내지 않고 해당 명령을 사용할 수 없다고 응답합니다. v2.1.274 이전에는 클라우드 세션과 루틴만 일치하지 않는 이름을 Claude에 보냈습니다. v2.1.273 이전에는 이들도 `Unknown command`로 응답했습니다. Claude Code는 `/`로 시작하는 모든 프롬프트를 명령으로 처리하지 않습니다. `/` 다음의 첫 단어가 Lean 문서 주석을 여는 `/--`처럼 문장 부호로 시작하거나 `/var/log/syslog` 같은 경로이면 프롬프트를 일반 메시지로 Claude에 보냅니다. v2.1.236 이전에는 명령 메뉴에 입력한 이름과 가까운 항목이 나열된 상태에서 `Enter`를 누르면 Claude Code가 그 항목을 실행했기 때문에, `/hepl` 같은 오타는 이 메시지를 표시하는 대신 `/help`를 실행했습니다. **해결 방법:** * 제안된 이름을 실행하거나, `/` 다음에 이름의 일부를 입력하여 이 세션에서 사용 가능한 명령을 확인합니다 * Claude Code가 문서화된 명령을 알 수 없는 명령으로 보고하면 [명령 참조](/docs/ko/commands)에서 해당 행에 명시된 요구 사항을 확인합니다

diff가 너무 커서 ultrareview를 할 수 없음

커밋되지 않은 변경 사항과 스테이징된 변경 사항을 포함하여 브랜치와 기본 브랜치 사이의 diff가 [ultrareview](/docs/ko/ultrareview)의 크기 제한을 초과했기 때문에, `/code-review ultra`와 `claude ultrareview` 하위 명령이 클라우드 세션 시작 전에 리뷰를 거부합니다. 거부된 리뷰는 무료 실행 횟수를 사용하지 않으며 사용량 크레딧도 청구되지 않습니다. 메시지에는 적용 중인 제한, diff 크기, 그리고 변경된 줄이 가장 많은 파일이 표시됩니다. v2.1.216 이전에는 메시지에 원시 diff 통계만 표시되었습니다. ```text theme={null} Diff is too large for ultrareview: 812 files, 96,410 lines changed (limits: 500 files, 8,000 lines). Largest files: package-lock.json (41,904 lines), dist/bundle.js (18,210 lines), src/generated/api.ts (9,876 lines). Pass a closer base branch (`/code-review ultra `) to narrow the scope, or split the change. ``` 풀 리퀘스트를 리뷰할 때도 같은 제한이 적용됩니다. 이 경우 메시지는 `PR # is too large for ultrareview`로 시작하며 PR의 파일 수와 줄 수가 표시됩니다. **해결 방법:** * `/code-review ultra develop`처럼 작업에 더 가까운 기본 브랜치를 전달하여 리뷰가 해당 브랜치와의 diff만 다루도록 합니다 * 변경 사항을 더 작은 브랜치로 나누고 각각 리뷰합니다. 메시지에 표시된 파일이 변경된 줄이 가장 많으므로, 먼저 해당 파일을 별도 브랜치로 옮기는 것부터 시작합니다.

기본 브랜치와의 merge-base를 찾을 수 없음

`/code-review ultra`와 `claude ultrareview` 하위 명령은 브랜치와 기본 브랜치 사이의 diff를 리뷰하며, 이를 위해서는 두 브랜치가 공유하는 커밋이 필요합니다. `git merge-base`가 그런 커밋을 찾지 못하면 Claude Code는 클라우드 세션 시작 전에 리뷰를 거부합니다. Claude Code가 완전한 것으로 확인할 수 있고 브랜치가 하나 이상 있는 클론에서는 거부하는 대신 [추적 중인 모든 파일을 리뷰](/docs/ko/ultrareview#diff-limits-and-fallbacks)하는 방식으로 폴백합니다. 이 거부는 기본 브랜치를 전혀 찾을 수 없을 때, Claude Code가 클론이 완전한지 확인할 수 없을 때, 또는 SHA-256 객체 형식처럼 전체 트리 diff가 불가능한 드문 저장소에서 표시됩니다. ```text theme={null} Could not find merge-base with main. Pass the base branch explicitly (e.g. `/code-review ultra develop`) or make sure you're in a git repo with a main branch. ``` 첫 문장 뒤의 힌트는 Claude Code가 관찰한 내용에 따라 달라집니다: * **기본 브랜치를 전달하지 않은 경우**: Claude Code는 저장소의 기본 브랜치와 비교했으며, 위 예시처럼 기본 브랜치를 명시적으로 전달하도록 제안합니다 * **클론에 이미 있는 기본 브랜치를 전달한 경우**: 힌트는 ``Make sure exists locally or on origin (try `git fetch origin `)``입니다 * **클론에 없는 기본 브랜치를 전달한 경우**: Claude Code는 비교하기 전에 origin에서 해당 브랜치를 fetch했습니다. 힌트는 `` was fetched from origin but shares no history with HEAD. If another branch is your real base, pass it explicitly (`/code-review ultra `)``입니다. Claude Code가 클론이 shallow인지 판단할 수 없는 경우에는 대신 `git fetch --unshallow origin`을 제안합니다. v2.1.221 이전에는 fetch한 모든 기본 브랜치에 대해 힌트가 `git fetch --unshallow origin`을 제안했으며, 완전한 클론에서 이 명령은 `fatal: --unshallow on a complete repository does not make sense`로 실패합니다. **해결 방법:** * 다른 브랜치가 실제 기본 브랜치라면 명시적으로 전달합니다: `/code-review ultra ` * 클론에 전체 히스토리가 없을 수 있다면 `git fetch --unshallow origin`을 실행하고 리뷰를 다시 실행합니다

체크아웃에 브랜치가 없음

체크아웃에는 커밋이 있어도 브랜치가 없을 수 있습니다. `git init`을 실행한 후 `git fetch `과 `git checkout FETCH_HEAD`를 실행하면 ref가 없는 detached HEAD 상태가 됩니다. Claude Code는 [ultrareview](/docs/ko/ultrareview)를 위해 저장소를 git 번들로 패키징하여 업로드하는데, 브랜치나 다른 ref가 없는 저장소는 번들로 만들 수 없으므로 `/code-review ultra`와 `claude ultrareview` 하위 명령이 클라우드 세션 시작 전에 리뷰를 거부합니다. ```text theme={null} Your checkout has no branches (detached HEAD only), which cloud review can't bundle. Create one first — `git checkout -b ` — then rerun /code-review ultra. ``` v2.1.221 이전에는 Claude Code가 이 체크아웃에서 추적 중인 모든 파일을 리뷰하려고 시도했고 업로드가 실패했습니다. **해결 방법:** * `git checkout -b `으로 현재 커밋에서 브랜치를 만든 다음 리뷰를 다시 실행합니다

Claude 계정에 연결된 GitHub 계정이 없음

`/code-review ultra ` 또는 `claude ultrareview `를 실행하면 Claude Code는 클라우드 세션을 만들기 전에 [Claude 계정에 연결된 GitHub 계정](/docs/ko/ultrareview#review-a-pull-request)이 PR의 저장소에 접근할 수 있는지 서버에 확인합니다. 연결된 계정이 없거나 연결이 만료되어 클라우드 클론이 실패할 것이므로 Claude Code가 실행을 거부합니다. 거부된 실행에 대해서는 무료 실행 횟수를 사용하거나 사용량 크레딧을 청구하지 않습니다. ```text theme={null} Ultrareview clones / in the cloud with the GitHub account connected to your Claude account, and none is connected (or the connection expired). To fix: run /web-setup to reuse your GitHub CLI login, or connect an account at https://claude.ai/connect-github — then re-run /code-review ultra 1234 (allow a minute after connecting). ``` 세션에서 [`/web-setup`](/docs/ko/web-quickstart#connect-from-your-terminal)을 사용할 수 없으면 메시지에는 claude.ai 링크만 표시됩니다. **해결 방법:** * `/web-setup`을 실행하여 GitHub CLI 로그인을 Claude 계정에 연결하거나, [claude.ai/connect-github](https://claude.ai/connect-github)에서 계정을 연결합니다 * 연결하고 1분 후에 리뷰를 다시 실행합니다 v2.1.248 이전에는 Claude Code가 실행 전에 이를 확인하지 않았습니다.

연결된 GitHub 계정이 저장소를 볼 수 없음

`/code-review ultra ` 또는 `claude ultrareview `를 실행했지만 [Claude 계정에 연결된 GitHub 계정](/docs/ko/ultrareview#review-a-pull-request)이 PR의 저장소를 읽을 수 없어 클라우드 클론이 실패할 것이므로 Claude Code가 실행을 거부합니다. 거부된 실행에 대해서는 무료 실행 횟수를 사용하거나 사용량 크레딧을 청구하지 않습니다. ```text theme={null} Your connected GitHub account can't see / — usually the Claude GitHub app isn't installed on or wasn't granted this repo (web-connected accounts need it for private repos), or a different GitHub account is connected. To fix: run /web-setup to reuse your GitHub CLI login, or install the app at https://github.com/apps/claude/installations/new — then re-run /code-review ultra 1234. ``` 세션에서 [`/web-setup`](/docs/ko/web-quickstart#connect-from-your-terminal)을 사용할 수 없으면 메시지에는 앱 설치만 표시됩니다. **해결 방법:** * 로컬 `gh` CLI가 저장소를 읽을 수 있다면 `/web-setup`을 실행하여 그 로그인을 Claude 계정에 연결합니다 * 변경 후 리뷰를 다시 실행합니다 v2.1.248 이전에는 Claude Code가 실행 전에 이를 확인하지 않았습니다.

GitHub App 사전 검사가 일시적으로 실패함

로컬 저장소에서 [클라우드 세션](/docs/ko/claude-code-on-the-web)을 시작했는데 두 단계가 함께 실패했습니다. Claude Code가 저장소 번들을 빌드하거나 업로드할 수 없었습니다. 업로드 전에 Claude Code는 클라우드 서비스가 GitHub에서 저장소를 클론할 수 있는지 확인했는데, 이 확인이 명확한 답 대신 네트워크 오류, 시간 초과, 일시적인 서버 오류처럼 재시도하면 해소될 수 있는 오류로 끝났습니다. 전체 메시지는 `Could not upload repo bundle ()`처럼 번들을 막은 원인으로 시작하고 사전 검사 문장으로 끝납니다: ```text theme={null} Could not upload repo bundle (). The GitHub App preflight failed transiently (network or service hiccup) — retry in a moment to start from GitHub instead ``` **해결 방법:** * 잠시 후 명령을 다시 실행합니다. GitHub 확인이 통과하면 Claude Code가 GitHub 클론에서 세션을 시작할 수 있으므로 실패한 업로드가 더 이상 실행을 막지 않습니다 * 재시도가 계속 실패하면 메시지 앞부분에 업로드를 막은 원인이 표시됩니다. 그 원인을 수정할 수 있다면 수정하여 로컬 저장소에서 세션을 시작할 수 있도록 합니다 v2.1.251 이전에는 GitHub 확인이 일시적으로만 실패한 경우에도 Claude Code가 메시지를 `Please set up GitHub on https://claude.ai/code`로 끝냈으며, 설정 조언으로는 일시적인 실패를 해결할 수 없었습니다.

저장소 업로드가 git 설정을 따를 수 없음

[로컬 저장소를 업로드하는 클라우드 세션](/docs/ko/claude-code-on-the-web#send-local-repositories-without-github) 또는 브랜치의 [ultrareview](/docs/ko/ultrareview)를 시작했는데, 파일에 어떤 속성 규칙이 적용되는지 결정하는 git 설정 중 하나를 업로드가 따를 수 없습니다. 업로드가 진행되어 규칙을 놓치면, clean 필터로 암호화되는 파일처럼 git이 저장 전에 변환하는 파일이 디스크에 있는 그대로 클라우드에 전달될 수 있습니다. 따라서 Claude Code는 업로드를 거부하며 아무것도 업로드되지 않습니다: ```text theme={null} Not uploading this working tree: core.ignoreCase (which decides whether .gitattributes patterns match file names regardless of letter case) is set in , and the upload cannot follow that setting, so a file git would change before storing it (to encrypt it, for example) could be uploaded as it is on disk. Move the core.ignoreCase line into this repository’s .git/config or directly into your ~/.gitconfig, then retry. ``` 메시지에는 설정과 설정된 위치가 표시되며, 해당하는 경우에 대한 해결 방법으로 끝납니다. `core.attributesFile`과 `attr.tree`에 대해서도 각각의 해결 방법과 함께 같은 거부가 표시됩니다. 메시지에는 git 구성이 `include` 또는 `includeIf` 지시문을 통해 불러오는 설정 파일이 표시될 수 있으며, 해당 지시문의 조건이 이 저장소에 적용되지 않는 경우에도 마찬가지입니다. **해결 방법:** * 메시지의 마지막 문장에 있는 해결 방법을 적용합니다

GitHub가 Claude 계정에 연결되어 있지 않음

`/autofix-pr` 등을 사용하여 로컬 저장소에서 [클라우드 세션](/docs/ko/claude-code-on-the-web)을 시작했습니다. Claude 계정에 연결된 GitHub 계정이 없거나 연결이 만료되었으므로 Claude Code가 실행을 거부합니다: ```text theme={null} GitHub isn't connected to your Claude account, so this repository can't be cloned in the cloud. Run /web-setup to connect with your GitHub CLI login, or connect on the web at https://claude.ai/connect-github ``` [`/schedule`](/docs/ko/routines)로 루틴을 만들 때는 같은 메시지가 저장소 이름이 포함된 설정 참고 사항으로 표시됩니다. 이 참고 사항은 루틴 생성을 막지 않습니다. **해결 방법:** * `/web-setup`을 실행하여 GitHub CLI 로그인을 Claude 계정에 연결하거나, [claude.ai/connect-github](https://claude.ai/connect-github)에서 계정을 연결합니다. 두 방법의 차이는 [GitHub 인증 옵션](/docs/ko/claude-code-on-the-web#github-authentication-options)을 참조하십시오. * 연결하고 1분 후에 명령을 다시 실행합니다 v2.1.268 이전에는 Claude Code가 이를 Claude GitHub App 확인의 일시적인 실패로 보고하고 재시도하거나 앱을 설치하도록 제안했지만, 둘 다 GitHub 계정을 연결하지 않습니다.

GitHub 조직 정책이 Claude를 차단하고 있음

Claude Code 프롬프트에서 [`/autofix-pr`](/docs/ko/claude-code-on-the-web#auto-fix-pull-requests)처럼 클라우드 세션을 시작하는 명령을 실행했습니다. Claude Code는 세션을 생성하기 전에 GitHub에서 Claude의 저장소 접근 권한을 확인하는데, GitHub 조직에 Claude를 차단하는 정책이 있어 GitHub가 이를 거부했습니다. Claude Code는 그 시점에서 중단하고 해당 정책을 명시하는 메시지를 표시합니다. IP 허용 목록이 접근을 차단하는 경우 메시지는 다음과 같습니다. ```text theme={null} Your GitHub organization has an IP allowlist that is blocking Claude. Add Claude's IP ranges to your GitHub allowlist. ``` 싱글 사인온이 차단하는 경우 메시지는 다음과 같습니다. ```text theme={null} Your GitHub organization requires single sign-on. Disconnect and reconnect GitHub on the Connectors page in Claude on the web, click Authorize next to your organization when GitHub asks, then try again. ``` Microsoft Entra ID 조건부 액세스 정책이 차단하는 경우 메시지는 다음과 같습니다. ```text theme={null} Your GitHub organization's identity provider (Microsoft Entra ID) has a Conditional Access policy that is blocking Claude. Ask your GitHub Enterprise or Entra ID admin to allow Claude in that policy. ``` **해결 방법:** * **IP 허용 목록**: GitHub 조직 또는 엔터프라이즈의 소유자에게 Anthropic의 아웃바운드 IP 주소를 허용하도록 요청합니다. 주소와 변경할 GitHub 설정은 [GitHub 허용 목록 및 방화벽](/docs/ko/network-config#github-allow-lists-and-firewalls)을 참조하십시오. * **싱글 사인온**: [claude.ai/customize/connectors](https://claude.ai/customize/connectors)에서 GitHub 연결을 해제한 다음 다시 연결합니다. GitHub가 요청하면 조직 옆의 **Authorize**를 클릭하여 새 연결이 해당 조직의 싱글 사인온에 대해 승인되도록 합니다. * **조건부 액세스 정책**: GitHub Enterprise 또는 Microsoft Entra ID 관리자에게 해당 정책에서 Claude를 허용하도록 요청합니다 * 변경 후 명령을 다시 실행합니다

싱글 사인온 승인 필요

[`/install-github-app`](/docs/ko/github-actions#quick-setup)을 실행하고 SAML 싱글 사인온을 적용하는 조직의 저장소를 선택했습니다. Claude Code는 설정 전에 GitHub CLI로 저장소 접근 권한을 확인하는데, `gh` 토큰이 아직 해당 조직에 대해 승인되지 않아 GitHub가 이 확인을 거부했습니다. 마법사는 승인 단계와 함께 경고를 표시합니다. ```text theme={null} Single sign-on authorization needed / belongs to an organization that enforces SAML single sign-on, and your GitHub CLI token isn't authorized for it yet. ``` **해결 방법:** * `gh auth refresh -h github.com -s repo,workflow`를 실행하여 `repo` 및 `workflow` 범위로 GitHub CLI 로그인을 다시 승인하고, GitHub가 싱글 사인온을 요청하면 조직을 승인합니다 * `GH_TOKEN`의 개인 액세스 토큰으로 인증하는 경우 [github.com/settings/tokens](https://github.com/settings/tokens)를 열고 토큰에서 **Configure SSO**를 선택한 다음 조직을 승인합니다 * `/install-github-app`을 다시 실행합니다 v2.1.273 이전에는 이 상황에서 Claude Code가 대신 `Admin permissions required` 경고를 표시했습니다.

대화를 재개하지 못함

Claude Code가 [`claude --resume` 선택기](/docs/ko/sessions#use-the-session-picker)에서 선택한 세션의 저장된 트랜스크립트를 읽거나 처리할 수 없어, 부분적으로 로드된 상태로 계속하는 대신 프로세스를 종료합니다. 메시지에는 재시도할 명령이 포함됩니다. ```text theme={null} Failed to resume the conversation. Run claude --resume to retry, or claude to start a new session. ``` Claude Code는 메시지를 표시한 후 코드 1로 종료됩니다. 실행 중인 세션 내의 `/resume` 선택기는 대신 대화에 `Failed to resume conversation`을 보고하며, 현재 세션은 계속 실행됩니다. v2.1.216 이전에는 `claude --resume` 선택기에서 재개에 실패하면 이 메시지를 표시하는 대신 `Resuming conversation…` 스피너에 무기한 머물러 있었습니다. **해결 방법:** * 메시지의 세션 ID로 `claude --resume `를 실행하여 재시도합니다 * v2.1.285 이전 버전에서 재시도가 같은 방식으로 실패하면 `claude update`를 실행하고 다시 재개합니다. 해당 버전은 저장된 트랜스크립트에 읽을 수 없는 항목이 포함되어 있으면 재개에 실패합니다. * 재시도가 다시 실패하면 `claude`를 실행하여 새 세션을 시작합니다

해당 세션 ID의 대화를 찾을 수 없음

`claude --resume `에 세션 ID를 전달했지만 일치하는 저장된 트랜스크립트가 없습니다. ```text theme={null} No conversation found with session ID: ``` Claude Code는 메시지를 표시한 후 코드 1로 종료됩니다. Claude Code는 ID를 찾기 위해 [현재 프로젝트를 먼저 검색한 다음 이 머신의 다른 모든 프로젝트를 검색](/docs/ko/sessions#resume-a-session)합니다. v2.1.223 이전에는 조회가 현재 프로젝트 디렉터리와 해당 git worktree에서 멈췄으므로, 세션이 마지막으로 작업한 디렉터리에서 재개해야 했습니다. 일반적인 원인: * **잘못 입력한 ID**: 비대화형 실행의 경우 ID는 [`--output-format json` 출력](/docs/ko/headless#get-structured-output)의 `session_id` 필드입니다 * **삭제된 트랜스크립트**: Claude Code는 [보존 정리 규칙](/docs/ko/claude-directory#cleaned-up-automatically)에 따라 [보존 기간](/docs/ko/sessions#where-transcripts-are-stored)(기본값 30일)이 지나면 트랜스크립트를 제거합니다 * **다른 머신**: Claude Code는 트랜스크립트를 로컬에 저장하므로 세션이 실행된 머신에서 재개해야 합니다 * **중복 사본**: `~/.claude/projects` 아래의 프로젝트 디렉터리를 복사하여 두 트랜스크립트가 같은 ID를 갖게 된 경우, Claude Code는 임의로 한 사본을 재개하는 대신 이 메시지를 보고합니다 **해결 방법:** * 대화형 세션의 경우 `claude --resume`으로 [세션 선택기](/docs/ko/sessions#use-the-session-picker)를 열고 `Ctrl+A`를 눌러 이 머신의 모든 프로젝트로 범위를 넓힌 다음 세션을 선택합니다 * `claude -p` 또는 [Agent SDK](/docs/ko/agent-sdk/overview)로 생성된 세션은 선택기에 나타나지 않으므로, 원래 실행에서 출력된 `session_id`와 ID를 다시 대조합니다

Claude Code가 이 세션의 트랜스크립트 파일을 읽을 때 Windows가 오류(EBADF)를 보고함

Windows에서 세션을 재개했고, 저장된 [트랜스크립트 파일](/docs/ko/sessions#where-transcripts-are-stored)은 정상적으로 열렸지만 이후 읽기가 시스템 오류 EBADF로 실패했습니다. 시스템 오류는 읽기가 실패한 이유를 알려주지 않으므로, 메시지에서 가능한 원인과 시도할 방법을 제안합니다. ```text theme={null} Windows reported an error (EBADF) when Claude Code read this session's transcript file, although the file had opened normally. This can happen when other software intercepts file reads — security, encryption or endpoint-management tools, for example. If it keeps happening for this conversation, try excluding the folder that holds Claude Code's session transcripts from such software (the .claude folder in your user profile, unless the app or CLAUDE_CONFIG_DIR points Claude Code elsewhere), or adding Claude Code to its allowed applications, then resume again. ``` 이 메시지는 `Failed to resume session `처럼 명령 자체의 실패 줄 다음에 표시됩니다. `claude --resume` 또는 [`claude -p`](/docs/ko/headless) 명령은 이를 표시한 후 코드 1로 종료됩니다. 세션 내에서 `/resume`을 실행한 경우에는 현재 세션이 계속 실행됩니다. **해결 방법:** * 보안, 암호화 또는 엔드포인트 관리 도구처럼 파일 읽기를 검사하거나 가로채는 소프트웨어에서 세션 트랜스크립트가 있는 폴더를 제외합니다. 트랜스크립트는 기본적으로 `%USERPROFILE%\.claude\projects` 아래에 있거나, [`CLAUDE_CONFIG_DIR`](/docs/ko/env-vars)이 지정하는 디렉터리 아래에 있습니다 * 제외를 추가할 수 없는 경우 대신 해당 소프트웨어의 허용된 애플리케이션에 Claude Code를 추가합니다 * 세션을 다시 재개합니다 v2.1.282 이전에는 실패 시 아무런 설명이 없었습니다. `claude --resume `는 `Failed to resume session `로 끝났고, `-p` 실행은 `Failed to resume session: EBADF: bad file descriptor, read`처럼 시스템 오류 텍스트만 출력했습니다.

이 세션에서 렌더러를 전환할 수 없음

렌더러를 전환하면 Claude Code는 프로세스를 다시 시작합니다. Claude Code가 다시 시작을 거부하는 세션에서 [`/tui`](/docs/ko/fullscreen#enable-fullscreen-rendering)를 실행했으므로, 전환하지 않고 아무것도 저장하지 않습니다. 표시되는 메시지로 원인을 알 수 있습니다. * `Cannot switch renderers while work is running in the background`: 백그라운드 셸이나 서브에이전트처럼 다시 시작하면 중단될 백그라운드 작업이 실행 중입니다. 작업이 끝날 때까지 기다리거나 [`/tasks`](/docs/ko/commands)로 중지한 다음 `/tui fullscreen` 또는 `/tui default`를 다시 실행합니다 * `Cannot switch renderers in this session`: 세션에 Claude Code가 다시 시작된 프로세스로 전달할 수 없는 제한이 있습니다. v2.1.234 이전에는 Claude Code가 그래도 다시 시작했고, 다시 실행된 세션은 해당 제한 없이 실행되었습니다 제한 메시지에서 괄호 안의 부분은 Claude Code가 발견한 제한을 나타냅니다. ```text theme={null} Cannot switch renderers in this session — it has restrictions a restart can't carry over (permission rules set for this session only). Nothing was changed. Running /tui fullscreen in a session started without them switches every later session too. ``` 메시지의 괄호 안에 표시될 수 있는 각 이유는 다음과 같습니다. * `launch flags: a custom system prompt, a tool allowlist, or restricted settings`: Claude Code가 다시 시작된 프로세스로 다시 전달하지 않는 플래그로 세션을 시작했습니다. 이러한 플래그에는 [`--system-prompt`](/docs/ko/cli-reference#cli-flags), `--system-prompt-file`, `--append-system-prompt-file`, [`--tools`](/docs/ko/cli-reference#cli-flags) 허용 목록, [`--setting-sources`](/docs/ko/cli-reference#cli-flags), [`--permission-prompt-tool`](/docs/ko/cli-reference#cli-flags)이 포함됩니다 * `permission rules set for this session only`: 훅 또는 SDK 호출자의 [권한 업데이트](/docs/ko/hooks#permission-update-entries)가 `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` 설정](/docs/ko/settings-reference#tui)을 저장합니다

Claude Desktop을 열 수 없음

세션에서 [`/desktop`](/docs/ko/desktop#coming-from-the-cli) 또는 그 별칭인 `/app`을 실행했거나, 셸에서 [`claude --desktop`](/docs/ko/cli-reference#cli-flags)을 실행했는데 Claude Code가 Claude Desktop을 열기 위해 사용하는 시스템 명령이 실패했습니다. `/desktop` 이후에는 세션이 터미널에 유지되며, `claude --desktop`은 `Error:` 접두사 없이 메시지를 출력하고 상태 1로 종료됩니다. 괄호 안의 텍스트는 실패한 명령을 나타내며, 종료 상태와 오류 출력의 첫 줄이 생성된 경우 함께 표시합니다. macOS에서는 이 예시처럼 해당 명령이 `open`이며, Windows에서는 `rundll32`입니다. ```text theme={null} Error: Couldn't open Claude Desktop (`open` exited 1: LSOpenURLsWithRole() failed for the URL claude://resume?session= with error -10814). Open Claude Desktop and try again. ``` **해결 방법:** * Claude Desktop을 직접 연 다음 `/desktop` 또는 `claude --desktop`을 다시 실행합니다 * 실패한 명령의 전체 오류 출력을 확인하려면 `/debug`로 디버그 로깅을 켜고 `/desktop`을 다시 실행하거나, `claude --desktop --debug-file `를 실행한 다음 디버그 로그를 확인합니다 v2.1.285 이전에는 메시지가 `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`](/docs/ko/terminal-config#enter-multiline-prompts)을 실행했지만 Claude Code가 Zed `keymap.json` 업데이트를 완료할 수 없어 파일을 그대로 두었습니다. 각 메시지는 키맵 경로를 명시하고, 직접 추가할 키보드 단축키 블록으로 끝납니다. ```text theme={null} Couldn't update your Zed keymap, so it was left unchanged. To add the binding yourself, add this block to the keymap array in : { "context": "Terminal", "bindings": { "shift-enter": ["terminal::SendText", "\u001b\r"] } } ``` 메시지의 첫 줄은 원인을 나타냅니다. * `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`을 다시 실행합니다 v2.1.247 이전에는 `/terminal-setup`이 `//` 주석이나 후행 쉼표를 사용하는 Zed 키맵을 파싱할 수 없었으며, 바인딩이 설치되었다고 보고하면서 전체 파일을 자체 바인딩만으로 대체했습니다. 이전 버전이 대체한 키맵을 복원하려면 [여러 줄 프롬프트 입력](/docs/ko/terminal-config#enter-multiline-prompts)에 설명된 `.bak` 백업 파일을 사용하십시오.

이 연결에서는 스킬 사용 보고서를 사용할 수 없음

휴대폰이나 브라우저에서 [Remote Control](/docs/ko/remote-control)을 통해 [`/skill-doctor`](/docs/ko/skills#find-unused-skills)를 실행했습니다. Claude Code는 Remote Control을 통해 스킬 사용 보고서를 보내지 않으며, 대신 다음 메시지로 응답합니다. ```text theme={null} Skill usage reports are not available on this connection. ``` **해결 방법:** * 세션이 실행 중인 머신의 터미널에서 `/skill-doctor`를 실행하거나, 해당 머신에서 `claude -p "/skill-doctor"`를 실행합니다

Remote Control을 통해서는 사용자 지정 출력 스타일을 선택할 수 없음

[Remote Control](/docs/ko/remote-control)을 통해 모바일 앱 또는 웹에서 [`/output-style`](/docs/ko/output-styles#change-your-output-style)을 실행했거나, 세션으로 전달된 메시지에 해당 명령이 포함되어 있었습니다. 이러한 턴은 계정 소유자가 보낸 것이 아닐 수 있으므로, Claude Code는 해당 턴에서 [기본 제공 스타일](/docs/ko/output-styles#built-in-output-styles)만 나열하고 선택하며, 명령이 스타일을 나열하거나 입력한 이름을 인식하지 못할 때마다 이 안내를 추가합니다. [사용자 지정 스타일](/docs/ko/output-styles#create-a-custom-output-style) 이름은 존재하지 않는 이름과 동일한 응답을 받습니다. ```text theme={null} Custom output styles can't be selected over Remote Control or from a relayed message. Select one in the session itself, or pick a built-in style here. ``` **해결 방법:** * 기본 제공 스타일을 선택합니다(예: `/output-style concise`) * 사용자 지정 스타일을 사용하려면 프로젝트의 `.claude/settings.local.json`에서 [`outputStyle`](/docs/ko/settings-reference#outputstyle)을 설정하거나, 세션 자체의 터미널이 있다면 그곳에서 `/output-style

오류 찾기

자동 재시도

Claude Code가 재시도하거나 대기하는 동안 보는 것

재시도 동작 조정

서버 오류

API 오류: 500 내부 서버 오류

API 오류: 반복된 529 오버로드 오류

요청 시간 초과

API에서 응답 없음

위의 응답이 불완전할 수 있음

자동 모드가 작업의 안전성을 결정할 수 없음

서버가 안전 판정을 반환하지 않음

API 오류로 인해 에이전트가 조기에 종료됨

사용 한도

You've hit your session limit

Usage credits required for 1M context

The prompt to confirm went unanswered

Server is temporarily limiting requests

Request rejected (429)

You've hit your monthly spend limit

Spend limit reached

Credit balance is too low

Could not update your spend limit

인증 오류

로그인되지 않음

인증 방법을 확인할 수 없음

유효하지 않은 API 키

apiKeyHelper 스크립트가 실패함

유효하지 않은 요청 헤더 값

이 조직이 비활성화됨

조직에서 API 키 인증을 비활성화함

조직에서 Claude 구독 액세스를 비활성화함

조직 정책에 의해 루틴이 비활성화됨

Remote Control에는 Anthropic API가 필요함

Remote Control이 로그인을 갱신하지 못함

로그인된 계정이 변경되어 Remote Control이 중지됨

세션을 실행하는 앱이 로그아웃하거나 계정을 전환하여 Remote Control이 중지됨

OAuth 토큰이 폐기되었거나 만료됨

API Error: 401 Invalid authentication credentials

로그인 만료

다른 Claude Code 프로세스가 갱신 중이어서 로그인을 갱신할 수 없음

로그인을 저장할 수 없음

OAuth 콜백 서버를 시작하지 못함

Claude 로그인이 수락되지 않음

아티팩트에는 claude.ai 로그인이 필요함

관리자 정책에 따라 Cloud 게이트웨이 로그인이 필요함

계정이 보류 상태임

Anthropic 프로필 로그인 만료

OAuth 범위 요구 사항

claude.ai가 세션 토큰을 거부함

MCP 서버에 다시 로그인해야 함

MCP 서버 URL이 없거나 유효한 URL이 아님

권한 부여 응답의 발급자 불일치

HTTPS가 아닌 토큰 엔드포인트로 자격 증명 전송 거부

AWS 자격 증명이 만료되었거나 유효하지 않음

AWS 인증 실패

Google Cloud 자격 증명이 만료되었거나 유효하지 않음

Google Cloud authentication failed

Microsoft Foundry authentication failed

Could not load AWS or Google Cloud credentials

AWS default-chain credential resolve timed out

Bedrock setup verification timed out waiting for AWS

Cloud gateway session expired

Sign-in timed out while waiting for you to continue

Gateway refused the request

네트워크 및 연결 오류

Unable to connect to API

Unable to connect to Anthropic services

Socket is closed

API returned an empty or malformed response

Streaming response ended before any complete data was received

Bedrock 스트리밍 응답에 예상치 못한 content-type이 있습니다

SSL 인증서 오류

클라우드 세션에서 호스트가 허용되지 않음

프록시가 연결을 거부했습니다

클라우드 환경 서비스가 빈 응답 또는 예상치 못한 응답을 반환했습니다

Couldn't reconnect to your Remote Control session

Sessions ended while this machine was offline

Couldn't share the transcript

Couldn't send feedback