21터미널에 표시되는 메시지를 아래 섹션과 일치시킵니다.21터미널에 표시되는 메시지를 아래 섹션과 일치시킵니다.
22 22
23| 메시지 | 섹션 |23| 메시지 | 섹션 |
24| :-------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------ |24| :------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------ |
25| `API Error: 500 Internal server error` | [서버 오류](#api-error-500-internal-server-error) |25| `API Error: 500 Internal server error` | [서버 오류](#api-error-500-internal-server-error) |
26| `API Error: Repeated 529 Overloaded errors` | [서버 오류](#api-error-repeated-529-overloaded-errors) |26| `API Error: Repeated 529 Overloaded errors` | [서버 오류](#api-error-repeated-529-overloaded-errors) |
27| `Request timed out` | [서버 오류](#request-timed-out), 또는 메시지에 인터넷 연결이 언급된 경우 [네트워크](#unable-to-connect-to-api) |27| `Request timed out` | [서버 오류](#request-timed-out), 또는 메시지에 인터넷 연결이 언급된 경우 [네트워크](#unable-to-connect-to-api) |
39| `Not logged in · Please run /login` | [인증](#not-logged-in) |39| `Not logged in · Please run /login` | [인증](#not-logged-in) |
40| `Could not resolve authentication method` | [인증](#could-not-resolve-authentication-method) |40| `Could not resolve authentication method` | [인증](#could-not-resolve-authentication-method) |
41| `Invalid API key` | [인증](#invalid-api-key) |41| `Invalid API key` | [인증](#invalid-api-key) |
42| `Your apiKeyHelper script is failing` | [인증](#your-apikeyhelper-script-is-failing) |
42| `This organization has been disabled` | [인증](#this-organization-has-been-disabled) |43| `This organization has been disabled` | [인증](#this-organization-has-been-disabled) |
43| `Your organization has disabled API key authentication` | [인증](#your-organization-has-disabled-api-key-authentication) |44| `Your organization has disabled API key authentication` | [인증](#your-organization-has-disabled-api-key-authentication) |
44| `Your organization has disabled Claude subscription access` | [인증](#your-organization-has-disabled-claude-subscription-access) |45| `Your organization has disabled Claude subscription access` | [인증](#your-organization-has-disabled-claude-subscription-access) |
45| `Routines are disabled by your organization's policy` | [인증](#routines-are-disabled-by-your-organizations-policy) |46| `Routines are disabled by your organization's policy` | [인증](#routines-are-disabled-by-your-organizations-policy) |
46| `Remote Control is only available when using Claude via api.anthropic.com` | [인증](#remote-control-requires-the-anthropic-api) |47| `Remote Control is only available when using Claude via api.anthropic.com` | [인증](#remote-control-requires-the-anthropic-api) |
47| `OAuth token revoked` / `OAuth token has expired` | [인증](#oauth-token-revoked-or-expired) |48| `OAuth token revoked` / `OAuth token has expired` | [인증](#oauth-token-revoked-or-expired) |
49| `Login expired · Please run /login` | [인증](#login-expired) |
50| `Failed to authenticate: OAuth session expired and could not be refreshed` | [인증](#login-expired) |
48| `does not meet scope requirement user:profile` | [인증](#oauth-scope-requirement) |51| `does not meet scope requirement user:profile` | [인증](#oauth-scope-requirement) |
49| `AWS credentials expired or invalid` | [인증](#aws-credentials-expired-or-invalid) |52| `AWS credentials expired or invalid` | [인증](#aws-credentials-expired-or-invalid) |
50| `AWS authentication failed` | [인증](#aws-authentication-failed) |53| `AWS authentication failed` | [인증](#aws-authentication-failed) |
54| `AWS default-chain credential resolve timed out` | [인증](#aws-default-chain-credential-resolve-timed-out) |
51| `Unable to connect to API` | [네트워크](#unable-to-connect-to-api) |55| `Unable to connect to API` | [네트워크](#unable-to-connect-to-api) |
52| `Waiting for API response · will retry in` | [자동 재시도](#automatic-retries), 또는 지속되는 경우 [네트워크](#unable-to-connect-to-api) |56| `Waiting for API response · will retry in` | [자동 재시도](#automatic-retries), 또는 지속되는 경우 [네트워크](#unable-to-connect-to-api) |
57| `Bedrock streaming response has content-type "..."; expected "application/vnd.amazon.eventstream"` | [네트워크](#bedrock-streaming-response-has-an-unexpected-content-type) |
53| `SSL certificate verification failed` | [네트워크](#ssl-certificate-errors) |58| `SSL certificate verification failed` | [네트워크](#ssl-certificate-errors) |
54| `SSL certificate error (...)` during login or startup | [네트워크](#ssl-certificate-errors) |59| `SSL certificate error (...)` during login or startup | [네트워크](#ssl-certificate-errors) |
55| `403` with `x-deny-reason: host_not_allowed` in a cloud or routine session | [네트워크](#host-not-allowed-in-a-cloud-session) |60| `403` with `x-deny-reason: host_not_allowed` in a cloud or routine session | [네트워크](#host-not-allowed-in-a-cloud-session) |
76| `--bg and --print conflict` | [명령줄 오류](#command-line-errors) |81| `--bg and --print conflict` | [명령줄 오류](#command-line-errors) |
77| `Error: --json-schema is not a valid JSON Schema` | [명령줄 오류](#command-line-errors) |82| `Error: --json-schema is not a valid JSON Schema` | [명령줄 오류](#command-line-errors) |
78| `Could not import <server>: <reason>` | [명령줄 오류](#could-not-import-a-server-from-claude-desktop) |83| `Could not import <server>: <reason>` | [명령줄 오류](#could-not-import-a-server-from-claude-desktop) |
84| `Error: MCP tool <name> (passed via --permission-prompt-tool) not found` | [명령줄 오류](#mcp-permission-prompt-tool-not-found) |
79| `Marketplace "<name>" is registered from an untrusted source` | [플러그인 오류](#marketplace-is-registered-from-an-untrusted-source) |85| `Marketplace "<name>" is registered from an untrusted source` | [플러그인 오류](#marketplace-is-registered-from-an-untrusted-source) |
86| `references ${user_config.*} in a shell-form command` | [플러그인 오류](#plugin-command-references-user-config) |
87| `Monitor "<name>" from plugin <plugin> references ${user_config.*} in its command` | [플러그인 오류](#plugin-command-references-user-config) |
88| `headersHelper for MCP server '<name>' references ${user_config.*}` | [플러그인 오류](#plugin-command-references-user-config) |
89| `would be spawned with zero tools — refusing` | [도구 오류](#agent-would-be-spawned-with-zero-tools) |
90| `File is covered by a Read deny rule in your permission settings` | [도구 오류](#file-is-covered-by-a-read-deny-rule) |
91| `Can't open MCP settings in a background session` | [백그라운드 세션 오류](#commands-refused-in-a-background-session) |
92| `CLAUDE_CODE_PROCESS_WRAPPER: launcher ...` | [백그라운드 세션 오류](#claude_code_process_wrapper-launcher-errors) |
80| `Ignoring N permissions.allow entries from ... this workspace has not been trusted` | [구성 경고](#workspace-has-not-been-trusted) |93| `Ignoring N permissions.allow entries from ... this workspace has not been trusted` | [구성 경고](#workspace-has-not-been-trusted) |
81| Responses seem lower quality than usual | [응답 품질](#responses-seem-lower-quality-than-usual) |94| Responses seem lower quality than usual | [응답 품질](#responses-seem-lower-quality-than-usual) |
82 95
86 99
87Claude Code는 오류를 표시하기 전에 일시적 오류를 재시도합니다. 서버 오류, 과부하 응답, 요청 시간 초과, 임시 429 스로틀, 끊어진 연결은 모두 지수 백오프를 사용하여 최대 10회 재시도됩니다. {/* min-version: 2.1.198 */}v2.1.198부터 이는 표시되는 출력이 없기 전에 응답 중간에 끊어지는 연결을 포함합니다. Claude Code는 동일한 백오프로 요청을 다시 발급하고 연결 오류로 중지하는 대신 턴이 계속됩니다. {/* min-version: 2.1.199 */}v2.1.199부터 계획의 할당량 헤더를 전달하지 않는 임시 429 스로틀도 claude.ai 구독으로 로그인할 때 재시도됩니다. 이전 버전은 API 키 및 엔터프라이즈 로그인에만 재시도했습니다.100Claude Code는 오류를 표시하기 전에 일시적 오류를 재시도합니다. 서버 오류, 과부하 응답, 요청 시간 초과, 임시 429 스로틀, 끊어진 연결은 모두 지수 백오프를 사용하여 최대 10회 재시도됩니다. {/* min-version: 2.1.198 */}v2.1.198부터 이는 표시되는 출력이 없기 전에 응답 중간에 끊어지는 연결을 포함합니다. Claude Code는 동일한 백오프로 요청을 다시 발급하고 연결 오류로 중지하는 대신 턴이 계속됩니다. {/* min-version: 2.1.199 */}v2.1.199부터 계획의 할당량 헤더를 전달하지 않는 임시 429 스로틀도 claude.ai 구독으로 로그인할 때 재시도됩니다. 이전 버전은 API 키 및 엔터프라이즈 로그인에만 재시도했습니다.
88 101
89두 가지 오류 클래스는 재시도할 수 없기 때문에 재시도되지 않습니다.102일부 오류 클래스는 재시도할 수 없기 때문에 재시도되지 않습니다.
90 103
91* {/* min-version: 2.1.199 */}v2.1.199부터 TLS 인증서 검증 실패(예: TLS 검사 프록시, 누락된 `NODE_EXTRA_CA_CERTS` 번들 또는 만료된 인증서)는 첫 번째 시도에서 실패하므로 전체 재시도 예산 후가 아닌 즉시 수정이 나타납니다. [SSL 인증서 오류](#ssl-certificate-errors)를 참조하십시오. 핸드셰이크 시간 초과와 같은 일시적 TLS 조건은 여전히 재시도됩니다.104* {/* min-version: 2.1.199 */}v2.1.199부터 TLS 인증서 검증 실패(예: TLS 검사 프록시, 누락된 `NODE_EXTRA_CA_CERTS` 번들 또는 만료된 인증서)는 첫 번째 시도에서 실패하므로 전체 재시도 예산 후가 아닌 즉시 수정이 나타납니다. [SSL 인증서 오류](#ssl-certificate-errors)를 참조하십시오. 핸드셰이크 시간 초과와 같은 일시적 TLS 조건은 여전히 재시도됩니다.
92* {/* min-version: 2.1.199 */}v2.1.199부터 Claude가 이미 표시되는 출력을 스트리밍한 후 도착하는 서버 오류는 부분 응답을 유지하고 [불완전한 응답 공지](#the-response-above-may-be-incomplete)를 추가합니다. 동일한 도구 호출을 두 번 실행할 수 있으므로 재시도하지 않습니다. 이전 버전은 부분 출력을 버리고 턴을 오류로 보고했습니다.105* {/* min-version: 2.1.199 */}v2.1.199부터 Claude가 이미 표시되는 출력을 스트리밍한 후 도착하는 서버 오류는 부분 응답을 유지하고 [불완전한 응답 공지](#the-response-above-may-be-incomplete)를 추가합니다. 동일한 도구를 두 번 실행할 수 있으므로 재시도하지 않습니다. 이전 버전은 부분 출력을 버리고 턴을 오류로 보고했습니다.
106* {/* min-version: 2.1.208 */}[Amazon Bedrock 스트리밍 응답에 예상치 못한 콘텐츠 유형](#bedrock-streaming-response-has-an-unexpected-content-type)은 첫 번째 시도에서 실패합니다. 게이트웨이 또는 프록시가 응답을 다시 작성하면 재시도도 동일한 방식으로 다시 작성하기 때문입니다. Claude Code v2.1.208 이상이 필요합니다.
93 107
94재시도하는 동안 스피너는 오류 레이블 뒤에 `Retrying in Ns · attempt x/y` 카운트다운을 표시합니다. 레이블은 즉시 조치할 수 있는 오류의 첫 번째 시도에서 구체적인 이유를 나타냅니다. 네트워크가 다운되었거나 TLS 핸드셰이크가 실패했거나 속도 제한에 도달했습니다. 다른 오류의 경우 처음에는 `API error`로 읽습니다. {/* min-version: 2.1.198 */}v2.1.198부터 세 번째 시도의 구체적인 이유로 전환되거나 `CLAUDE_CODE_MAX_RETRIES`가 3개 미만을 허용할 때 최종 시도에서 전환됩니다. 이전 버전은 최종 시도에서만 전환됩니다.108재시도하는 동안 스피너는 오류 레이블 뒤에 `Retrying in Ns · attempt x/y` 카운트다운을 표시합니다. 레이블은 즉시 조치할 수 있는 오류의 첫 번째 시도에서 구체적인 이유를 나타냅니다. 네트워크가 다운되었거나 TLS 핸드셰이크가 실패했거나 속도 제한에 도달했습니다. 다른 오류의 경우 처음에는 `API error`로 읽습니다. {/* min-version: 2.1.198 */}v2.1.198부터 세 번째 시도의 구체적인 이유로 전환되거나 `CLAUDE_CODE_MAX_RETRIES`가 3개 미만을 허용할 때 최종 시도에서 전환됩니다. 이전 버전은 최종 시도에서만 전환됩니다.
95 109
285 299
286Claude Code는 메시지에 표시된 재설정 시간까지 추가 요청을 차단합니다. 세션 및 주간 한도는 모든 모델에서 공유되므로 모델을 전환해도 액세스가 복구되지 않습니다. Opus 한도는 Opus 요청에만 적용되므로 `/model`로 다른 모델로 전환하면 계속 작업할 수 있습니다.300Claude Code는 메시지에 표시된 재설정 시간까지 추가 요청을 차단합니다. 세션 및 주간 한도는 모든 모델에서 공유되므로 모델을 전환해도 액세스가 복구되지 않습니다. Opus 한도는 Opus 요청에만 적용되므로 `/model`로 다른 모델로 전환하면 계속 작업할 수 있습니다.
287 301
302사용량은 세션 및 주간 허용량에 동시에 계산됩니다. 대규모 워크플로우 팬아웃과 같은 단일 대량 활동 버스트는 세션 윈도우가 재설정되기 전에 주간 허용량을 소진할 수 있습니다.
303
288**수행할 작업:**304**수행할 작업:**
289 305
290* 오류에 표시된 재설정 시간까지 기다립니다306* 오류에 표시된 재설정 시간까지 기다립니다
430* 키가 [`apiKeyHelper`](/ko/settings#available-settings) 스크립트에서 오는 경우 스크립트를 직접 실행하여 stdout에 유효한 키를 인쇄하는지 확인합니다.446* 키가 [`apiKeyHelper`](/ko/settings#available-settings) 스크립트에서 오는 경우 스크립트를 직접 실행하여 stdout에 유효한 키를 인쇄하는지 확인합니다.
431* `/status`를 실행하여 Claude Code가 실제로 사용 중인 자격증명 소스를 확인합니다.447* `/status`를 실행하여 Claude Code가 실제로 사용 중인 자격증명 소스를 확인합니다.
432 448
449<h3 id="your-apikeyhelper-script-is-failing">
450 apiKeyHelper 스크립트가 실패하고 있습니다
451</h3>
452
453[`apiKeyHelper`](/ko/settings#available-settings) 설정에 구성된 명령이 오류로 종료되었거나, 시간 초과되었거나, stdout에 아무것도 인쇄하지 않았습니다. 스크립트에서 키가 없으면 요청이 플레이스홀더 자격증명으로 API에 도달하고 API가 `401`로 거부합니다.
454
455```text theme={null}
456Your apiKeyHelper script is failing · This usually means you need to re-authenticate with your provider · Run /status to see the script's error output
457```
458
459Claude Code는 스크립트를 다시 실행하고 이 메시지를 표시하기 전에 요청을 최대 2회 더 재시도하므로 실패가 3번의 시도 내에 표시됩니다. {/* min-version: 2.1.208 */}v2.1.208 이전에는 Claude Code가 전체 [재시도 예산](#automatic-retries)을 플레이스홀더 자격증명으로 요청을 재전송하는 데 사용한 후 스크립트 실패 대신 일반 `401` 인증 오류를 보고했습니다.
460
461`/login`을 실행해도 도움이 되지 않습니다. 설정이 있는 한 헬퍼의 출력이 저장된 로그인보다 [우선순위를 가집니다](/ko/authentication#authentication-precedence).
462
463**수행할 작업:**
464
465* `apiKeyHelper`에 구성된 명령을 셸에서 직접 실행하여 실패를 재현합니다.
466* 명령이 만료된 세션을 보고하면 자격증명 공급자로 다시 인증합니다(예: SSO 또는 비밀 저장소에 다시 로그인).
467* 명령이 stdout에 키를 인쇄하고 코드 0으로 종료하도록 수정합니다. [apiKeyHelper로 자격증명 회전](/ko/llm-gateway-connect#rotate-credentials-with-apikeyhelper)에서 작동하는 설정을 참조합니다.
468* `/status`를 실행하여 `apiKeyHelper`가 활성 자격증명 소스인지 확인합니다. 명령이 실패할 때마다 종료 코드와 오류 출력이 터미널의 `Cloud authentication` 패널에 나타납니다.
469
433<h3 id="this-organization-has-been-disabled">470<h3 id="this-organization-has-been-disabled">
434 이 조직이 비활성화되었습니다471 이 조직이 비활성화되었습니다
435</h3>472</h3>
453 조직에서 API 키 인증을 비활성화했습니다490 조직에서 API 키 인증을 비활성화했습니다
454</h3>491</h3>
455 492
493{/* min-version: 2.1.169 */}}
456이 메시지는 Claude Code v2.1.169 이상이 필요합니다. Console 조직의 관리자가 API 키 인증을 비활성화했으므로 API가 Claude Code가 보내는 키를 거부합니다. `·` 뒤의 복구 힌트는 키가 어디에서 왔는지에 따라 다릅니다:494이 메시지는 Claude Code v2.1.169 이상이 필요합니다. Console 조직의 관리자가 API 키 인증을 비활성화했으므로 API가 Claude Code가 보내는 키를 거부합니다. `·` 뒤의 복구 힌트는 키가 어디에서 왔는지에 따라 다릅니다:
457 495
458```text theme={null}496```text theme={null}
532 570
533저장된 로그인이 더 이상 유효하지 않습니다. 취소된 토큰은 모든 곳에서 로그아웃했거나 관리자가 액세스를 제거했음을 의미하고, 만료된 토큰은 자동 새로 고침이 세션 중에 실패했음을 의미합니다.571저장된 로그인이 더 이상 유효하지 않습니다. 취소된 토큰은 모든 곳에서 로그아웃했거나 관리자가 액세스를 제거했음을 의미하고, 만료된 토큰은 자동 새로 고침이 세션 중에 실패했음을 의미합니다.
534 572
573두 메시지 모두 Claude Code가 보낸 요청에 대해 API가 반환한 거부를 보고합니다. 저장된 로그인이 실패한 새로 고침 후 이미 지워진 경우 대신 [로그인 만료됨](#login-expired)을 봅니다.
574
535```text theme={null}575```text theme={null}
536OAuth token revoked · Please run /login576OAuth token revoked · Please run /login
537OAuth token has expired · Please run /login577OAuth token has expired · Please run /login
545* 시작 간에 반복적인 로그인 프롬프트의 경우 [문제 해결](/ko/troubleshoot-install#not-logged-in-or-token-expired)의 시스템 시계 및 macOS Keychain 확인을 참조합니다.585* 시작 간에 반복적인 로그인 프롬프트의 경우 [문제 해결](/ko/troubleshoot-install#not-logged-in-or-token-expired)의 시스템 시계 및 macOS Keychain 확인을 참조합니다.
546* `403 Forbidden` 및 OAuth 브라우저 문제를 포함한 다른 실패의 경우 [로그인 및 인증](/ko/troubleshoot-install#login-and-authentication)을 참조합니다.586* `403 Forbidden` 및 OAuth 브라우저 문제를 포함한 다른 실패의 경우 [로그인 및 인증](/ko/troubleshoot-install#login-and-authentication)을 참조합니다.
547 587
588<h3 id="login-expired">
589 로그인 만료됨
590</h3>
591
592Claude Code가 저장된 claude.ai 또는 Claude Console 로그인을 갱신하려고 했고 OAuth 서비스가 저장된 새로 고침 토큰을 거부했으므로 Claude Code가 저장된 자격증명을 지웠습니다. 그 후 각 요청은 API에 도달하기 전에 로컬에서 중지됩니다. 새 자격증명을 만들 수 있는 것은 `/login`뿐이기 때문입니다. {/* min-version: 2.1.206 */}v2.1.206 이전에는 Claude Code가 환경에 남아 있는 모든 자격증명으로 요청을 어쨌든 보냈고 모든 모델이 로그인하라는 프롬프트 대신 [선택한 모델에 문제가 있습니다](#theres-an-issue-with-the-selected-model) 또는 401로 실패했습니다.
593
594```text theme={null}
595Login expired · Please run /login
596```
597
598[비대화형 모드](/ko/headless)(`-p`) 및 [Agent SDK](/ko/agent-sdk/overview)에서 메시지는 다음과 같이 읽히며 구조화된 오류 코드는 `authentication_failed`입니다:
599
600```text theme={null}
601Failed to authenticate: OAuth session expired and could not be refreshed
602```
603
604이는 [OAuth 토큰이 취소되었거나 만료되었습니다](#oauth-token-revoked-or-expired)와 동일한 상태가 아닙니다. 이러한 메시지는 API가 반환한 401을 보고합니다. Claude Code 자체는 이미 갱신하지 못한 로그인에 대해 `Login expired`를 생성하므로 요청을 보내지 않습니다.
605
606API 키, [`CLAUDE_CODE_OAUTH_TOKEN`](/ko/env-vars) 또는 타사 공급자로 인증된 세션은 저장된 로그인을 사용하지 않으며 이 메시지를 절대 보지 않습니다.
607
608**수행할 작업:**
609
610* `/login`을 실행하여 다시 로그인합니다. 로그인하지 않고 재시도하면 모든 요청에서 동일한 메시지가 표시됩니다.
611* 비대화형 모드에서 동일한 환경에서 `claude`를 실행하고 `/login`을 완료한 후 명령을 다시 실행합니다. 대화형으로 로그인할 수 없는 자동화의 경우 `ANTHROPIC_API_KEY`로 인증하거나 [`claude setup-token`으로 장기 토큰을 생성합니다](/ko/authentication#generate-a-long-lived-token).
612* 로그인이 계속 실패하면 [로그인 및 인증](/ko/troubleshoot-install#login-and-authentication)을 참조합니다.
613
548<h3 id="oauth-scope-requirement">614<h3 id="oauth-scope-requirement">
549 OAuth 범위 요구사항615 OAuth 범위 요구사항
550</h3>616</h3>
603* 자격증명이 최신이면 [IAM 구성](/ko/amazon-bedrock#iam-configuration)의 IAM 권한이 사용 중인 ID에 연결되어 있고 선택한 모델이 계정 및 지역에 대해 활성화되어 있는지 확인합니다.669* 자격증명이 최신이면 [IAM 구성](/ko/amazon-bedrock#iam-configuration)의 IAM 권한이 사용 중인 ID에 연결되어 있고 선택한 모델이 계정 및 지역에 대해 활성화되어 있는지 확인합니다.
604* `aws sts get-caller-identity`를 실행하여 요청이 어떤 ID를 사용하는지 확인합니다. 오래된 `AWS_PROFILE` 또는 기본 프로필은 권한 불일치의 일반적인 원인입니다.670* `aws sts get-caller-identity`를 실행하여 요청이 어떤 ID를 사용하는지 확인합니다. 오래된 `AWS_PROFILE` 또는 기본 프로필은 권한 불일치의 일반적인 원인입니다.
605 671
672<h3 id="aws-default-chain-credential-resolve-timed-out">
673 AWS 기본 체인 자격증명 확인 시간 초과
674</h3>
675
676AWS 기본 자격증명 공급자 체인이 60초 내에 자격증명을 생성하지 못했으므로 Claude Code가 확인을 중지하고 요청을 실패했습니다. 실패는 로컬 자격증명 확인입니다. 요청이 [Amazon Bedrock](/ko/amazon-bedrock), [AWS의 Claude Platform](/ko/claude-platform-on-aws) 또는 [Mantle 엔드포인트](/ko/amazon-bedrock#use-the-mantle-endpoint)에 도달하지 않았습니다. Claude Code는 이 오류가 표시되기 전에 [자격증명 캐시](/ko/amazon-bedrock#credential-caching-and-resolution-timeout)를 지우고 반복 시도 전에 재시도하므로 체인이 반복 시도에서 정체되었습니다.
677
678```text theme={null}
679API Error: AWS default-chain credential resolve timed out
680```
681
682일반적인 원인은 AWS 프로필의 `credential_process` 명령이 받을 수 없는 입력을 기다리는 것이고, 인스턴스 메타데이터 서비스(IMDS)가 체인의 프로브에 응답하지 않는 컨테이너 또는 VM입니다. {/* min-version: 2.1.207 */}v2.1.207 이전에는 정체된 체인이 요청을 무한정 기다리게 했으며 이 메시지로 실패하지 않았습니다.
683
684**수행할 작업:**
685
686* 동일한 셸에서 동일한 `AWS_PROFILE`로 `aws sts get-caller-identity`를 실행합니다. 또한 중단되면 프로필을 수정합니다. 대화형으로 프롬프트하는 `credential_process` 명령이 일반적인 원인입니다.
687* Claude Code를 시작하기 전에 로그인 단계를 완료합니다(예: `aws sso login --profile myprofile`). 그러면 체인이 브라우저 흐름을 기다리지 않고 로컬 SSO 캐시에서 확인됩니다.
688* 체인이 `aws-vault`와 같은 래퍼를 통한 MFA가 있는 SSO와 같이 60초 이상이 필요한 대화형 로그인을 실행하면 [`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/ko/env-vars)로 밀리초 단위로 제한을 높입니다.
689
606<h2 id="network-and-connection-errors">690<h2 id="network-and-connection-errors">
607 네트워크 및 연결 오류691 네트워크 및 연결 오류
608</h2>692</h2>
609 693
610이러한 오류는 Claude Code의 네트워크 요청이 목적지에 도달하지 못했음을 의미합니다. 일반적으로 로컬 네트워크, 프록시 또는 방화벽, 또는 클라우드 환경의 네트워크 정책에서 발생합니다.694이러한 오류는 Claude Code의 네트워크 요청이 목적지에 도달하지 못했거나, Claude Code와 API 사이의 무언가가 응답을 변경했음을 의미합니다. 일반적으로 로컬 네트워크, 프록시 또는 방화벽, 또는 클라우드 환경의 네트워크 정책에서 발생합니다.
611 695
612<h3 id="unable-to-connect-to-api">696<h3 id="unable-to-connect-to-api">
613 API에 연결할 수 없음697 API에 연결할 수 없음
640* macOS에서 연결이 끊어지거나 제거된 VPN 클라이언트는 터널 인터페이스 또는 라우팅 규칙을 남길 수 있습니다. `ifconfig`에서 오래된 `utun` 인터페이스를 확인하고 시스템 설정에서 VPN의 네트워크 확장을 제거합니다.724* macOS에서 연결이 끊어지거나 제거된 VPN 클라이언트는 터널 인터페이스 또는 라우팅 규칙을 남길 수 있습니다. `ifconfig`에서 오래된 `utun` 인터페이스를 확인하고 시스템 설정에서 VPN의 네트워크 확장을 제거합니다.
641* Docker Desktop 및 유사한 컨테이너 런타임은 아웃바운드 트래픽을 가로챌 수 있습니다. 이를 종료하고 다시 시도하여 이를 배제합니다.725* Docker Desktop 및 유사한 컨테이너 런타임은 아웃바운드 트래픽을 가로챌 수 있습니다. 이를 종료하고 다시 시도하여 이를 배제합니다.
642 726
727<h3 id="bedrock-streaming-response-has-an-unexpected-content-type">
728 Bedrock 스트리밍 응답에 예상치 못한 content-type이 있음
729</h3>
730
731Claude Code와 [Amazon Bedrock](/ko/amazon-bedrock) 사이의 게이트웨이 또는 프록시가 스트리밍 응답 본문 또는 해당 `Content-Type` 헤더를 변환하고 있습니다. Amazon Bedrock은 응답을 `application/vnd.amazon.eventstream`으로 스트리밍하며, Claude Code는 읽을 수 없는 본문을 디코딩하는 대신 다른 content-type을 보고하는 성공적인 스트리밍 응답을 거부합니다. 요청은 재시도되지 않습니다.
732
733```text theme={null}
734Bedrock streaming response has content-type "text/event-stream"; expected "application/vnd.amazon.eventstream". A gateway or proxy between Claude Code and Bedrock is likely transforming the response body — Bedrock's binary event-stream format must be passed through unmodified. Set CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1 to suppress this check while the gateway is being fixed.
735```
736
737{/* min-version: 2.1.208 */}v2.1.208 이전에는 동일한 잘못된 구성이 전체 응답이 버퍼링된 후 `API Error: Truncated event message received`로 나타났습니다.
738
739**수행할 작업:**
740
741* 게이트웨이를 구성하여 `InvokeModelWithResponseStream` 응답 본문 및 해당 `Content-Type` 헤더를 수정되지 않은 상태로 전달합니다. 스트림을 서버 전송 이벤트로 다시 내보내는 중개자가 일반적인 원인입니다.
742* 게이트웨이가 헤더만 다시 쓰고 바이너리 본문을 그대로 전달하는 경우 게이트웨이가 수정될 때까지 확인을 건너뛰도록 [`CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD=1`](/ko/env-vars)을 설정합니다. [게이트웨이 또는 프록시 뒤의 스트리밍 오류](/ko/amazon-bedrock#streaming-errors-behind-a-gateway-or-proxy)를 참조합니다.
743
643<h3 id="ssl-certificate-errors">744<h3 id="ssl-certificate-errors">
644 SSL 인증서 오류745 SSL 인증서 오류
645</h3>746</h3>
859* **Agent SDK**: 모델이 프로그래밍 방식으로 설정되므로 오류 텍스트는 힌트를 생략합니다. TypeScript에서 [`Options`의 `model`](/ko/agent-sdk/typescript#options)을 설정하거나 Python에서 [`ClaudeAgentOptions(model=...)`](/ko/agent-sdk/python#claudeagentoptions)을 설정하고, 구조화된 `model_not_found` 오류를 처리하여 자신의 재시도 또는 모델 선택기를 표시합니다.960* **Agent SDK**: 모델이 프로그래밍 방식으로 설정되므로 오류 텍스트는 힌트를 생략합니다. TypeScript에서 [`Options`의 `model`](/ko/agent-sdk/typescript#options)을 설정하거나 Python에서 [`ClaudeAgentOptions(model=...)`](/ko/agent-sdk/python#claudeagentoptions)을 설정하고, 구조화된 `model_not_found` 오류를 처리하여 자신의 재시도 또는 모델 선택기를 표시합니다.
860* 전체 버전이 지정된 ID 대신 `sonnet` 또는 `opus`와 같은 별칭을 사용합니다. 별칭은 유지 관리되는 기본값으로 확인되므로 오래되지 않습니다. [모델 구성](/ko/model-config)을 참조합니다.961* 전체 버전이 지정된 ID 대신 `sonnet` 또는 `opus`와 같은 별칭을 사용합니다. 별칭은 유지 관리되는 기본값으로 확인되므로 오래되지 않습니다. [모델 구성](/ko/model-config)을 참조합니다.
861* 잘못된 모델이 CLI에서 계속 반환되면 어딘가에 오래된 ID가 설정되어 있습니다. [우선 순위 순서](/ko/model-config#setting-your-model)로 확인합니다: `--model` 플래그, `ANTHROPIC_MODEL` 환경 변수, 그런 다음 `.claude/settings.local.json`의 `model` 필드, 프로젝트의 `.claude/settings.json` 및 `~/.claude/settings.json`. 오래된 값을 제거하면 Claude Code가 계정 기본값으로 폴백됩니다.962* 잘못된 모델이 CLI에서 계속 반환되면 어딘가에 오래된 ID가 설정되어 있습니다. [우선 순위 순서](/ko/model-config#setting-your-model)로 확인합니다: `--model` 플래그, `ANTHROPIC_MODEL` 환경 변수, 그런 다음 `.claude/settings.local.json`의 `model` 필드, 프로젝트의 `.claude/settings.json` 및 `~/.claude/settings.json`. 오래된 값을 제거하면 Claude Code가 계정 기본값으로 폴백됩니다.
963* {/* min-version: 2.1.206 */}Claude Code는 만료된 claude.ai 로그인을 [로그인 만료됨](#login-expired)으로 보고하며, 이 오류로는 보고하지 않습니다. v2.1.206 이전에는 더 이상 새로 고칠 수 없는 만료된 로그인이 이 오류로 모든 모델에 실패했습니다. 이전 버전에서 이것을 보면 `/login`을 실행합니다.
862* Google Cloud의 Agent Platform 배포의 경우 [Google Cloud의 Agent Platform 문제 해결](/ko/google-vertex-ai#troubleshooting)을 참조합니다.964* Google Cloud의 Agent Platform 배포의 경우 [Google Cloud의 Agent Platform 문제 해결](/ko/google-vertex-ai#troubleshooting)을 참조합니다.
863 965
864<h3 id="model-is-not-a-recognized-model-id">966<h3 id="model-is-not-a-recognized-model-id">
1070 \--bg와 --print 간의 충돌1172 \--bg와 --print 간의 충돌
1071</h3>1173</h3>
1072 1174
1073이 메시지는 Claude Code v2.1.198 이상이 필요합니다. 동일한 `claude` 호출에서 `--bg`를 `-p` 또는 `--print`와 결합했습니다. `--bg`는 나중에 `claude agents`로 연결할 수 있는 [백그라운드 세션](/ko/agent-view#from-your-shell)을 시작하는 반면, `--print`는 [비대화형](/ko/headless)으로 실행되며 `claude agents`가 연결하는 대화형 세션을 시작하지 않습니다. v2.1.198 이전에는 이 조합이 자동으로 연결할 수 없는 백그라운드 작업을 생성했습니다.1175이 메시지는 Claude Code v2.1.198 이상이 필요합니다. 동일한 `claude` 호출에서 `--bg`를 `-p` 또는 `--print`와 결합했습니다. `--bg`는 나중에 `claude agents`로 연결할 수 있는 [백그라운드 세션](/ko/agent-view#from-your-shell)을 시작하는 반면, `--print`는 [비대화형](/ko/headless)으로 실행되며 `claude agents`가 연결하는 대화형 세션을 시작하지 않습니다. v2.1.198 이전에는 이 조합이 연결할 수 없는 백그라운드 작업을 자동으로 생성했습니다.
1074 1176
1075```text theme={null}1177```text theme={null}
1076--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 '<task>'`.1178--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 '<task>'`.
1079**수행할 작업:**1181**수행할 작업:**
1080 1182
1081* `-p` 또는 `--print`를 제거합니다. `--bg`는 프롬프트를 위치 인수로 사용하므로 `claude --bg "<task>"`가 완전한 명령입니다. [셸에서 새 에이전트 디스패치](/ko/agent-view#from-your-shell)를 참조하세요.1183* `-p` 또는 `--print`를 제거합니다. `--bg`는 프롬프트를 위치 인수로 사용하므로 `claude --bg "<task>"`가 완전한 명령입니다. [셸에서 새 에이전트 디스패치](/ko/agent-view#from-your-shell)를 참조하세요.
1082* 프롬프트를 비대화형으로 실행하고 백그라운드 세션을 만드는 대신 결과를 출력하려면 `--bg`를 제거하고 `claude -p "<task>"`를 실행합니다.1184* 프롬프트를 비대화형으로 실행하고 백그라운드 세션을 생성하는 대신 결과를 출력하려면 `--bg`를 제거하고 `claude -p "<task>"`를 실행합니다.
1083 1185
1084<h3 id="the-json-schema-value-is-not-a-valid-json-schema">1186<h3 id="the-json-schema-value-is-not-a-valid-json-schema">
1085 \--json-schema 값이 유효한 JSON Schema가 아닙니다1187 \--json-schema 값이 유효한 JSON Schema가 아닙니다
1086</h3>1188</h3>
1087 1189
1088[비대화형 모드](/ko/headless#get-structured-output)에서 [`--json-schema`](/ko/cli-reference#cli-flags)에 전달한 스키마가 JSON Schema 컴파일에 실패했으므로 `claude`는 프롬프트를 실행하는 대신 코드 1로 종료됩니다. v2.1.205 이전에는 유효하지 않은 스키마가 오류 없이 구조화되지 않은 출력을 생성했으며, `format` 키워드를 사용한 모든 스키마는 유효하지 않은 것으로 처리되었습니다.1190[`--json-schema`](/ko/cli-reference#cli-flags)에 전달한 스키마가 [비대화형 모드](/ko/headless#get-structured-output)에서 JSON Schema 컴파일에 실패했으므로 `claude`는 프롬프트를 실행하는 대신 종료 코드 1로 종료됩니다. v2.1.205 이전에는 유효하지 않은 스키마가 오류 없이 구조화되지 않은 출력을 생성했으며, `format` 키워드를 사용한 모든 스키마는 유효하지 않은 것으로 처리되었습니다.
1089 1191
1090```text theme={null}1192```text theme={null}
1091Error: --json-schema is not a valid JSON Schema: data/type must be equal to one of the allowed values1193Error: --json-schema is not a valid JSON Schema: data/type must be equal to one of the allowed values
1093 1195
1094두 번째 콜론 뒤의 텍스트는 검증자의 진단이며 실패한 키워드 또는 위치를 나타냅니다. `"format": "email"`과 같은 `format` 키워드를 사용하는 스키마는 유효합니다. Claude Code는 `format`을 주석으로 허용하며 이를 적용하지 않습니다.1196두 번째 콜론 뒤의 텍스트는 검증자의 진단이며 실패한 키워드 또는 위치를 나타냅니다. `"format": "email"`과 같은 `format` 키워드를 사용하는 스키마는 유효합니다. Claude Code는 `format`을 주석으로 허용하며 이를 적용하지 않습니다.
1095 1197
1096Claude Code는 스키마 컴파일 전에 두 가지 검사를 실행합니다. 구문 분석할 수 없는 JSON 값을 `Error: --json-schema is not valid JSON`으로 거부하고, 객체가 아닌 유효한 JSON을 `Error: --json-schema must be a JSON object`로 거부합니다.1198Claude Code는 스키마 컴파일 전에 두 가지 검사를 실행합니다. 구문 분석할 수 없는 JSON 값은 `Error: --json-schema is not valid JSON`으로 거부하고, 객체가 아닌 유효한 JSON은 `Error: --json-schema must be a JSON object`로 거부합니다.
1097 1199
1098**수행할 작업:**1200**수행할 작업:**
1099 1201
1100* 진단이 명시한 스키마 부분을 수정한 후 명령을 다시 실행합니다.1202* 진단이 나타내는 스키마 부분을 수정한 후 명령을 다시 실행합니다.
1101* 진단이 `schema too large`인 경우 스키마의 중첩 및 `$ref` 재사용을 줄입니다.1203* 진단이 `schema too large`인 경우 스키마의 중첩 및 `$ref` 재사용을 줄입니다.
1102* [구조화된 출력 가져오기](/ko/headless#get-structured-output)에서 작동하는 스키마 및 명령을 참조하세요.1204* [구조화된 출력 가져오기](/ko/headless#get-structured-output)에서 작동하는 스키마 및 명령을 참조하세요.
1103 1205
1105 Claude Desktop에서 서버를 가져올 수 없습니다1207 Claude Desktop에서 서버를 가져올 수 없습니다
1106</h3>1208</h3>
1107 1209
1108Claude Code는 `claude mcp add-from-claude-desktop`에서 선택한 서버 중 하나를 추가할 수 없습니다. 명령은 여전히 다른 선택된 서버를 가져오고 추가할 수 없는 각 서버마다 한 줄을 출력합니다. v2.1.205 이전에는 실패한 첫 번째 서버가 가져오기를 중지했으며 선택된 서버 중 어느 것도 추가되지 않았습니다.1210Claude Code는 `claude mcp add-from-claude-desktop`에서 선택한 서버 중 하나를 추가할 수 없습니다. 명령은 여전히 다른 선택된 서버를 가져오고 추가할 수 없는 각 서버마다 한 줄을 출력합니다. v2.1.205 이전에는 실패한 첫 번째 서버가 가져오기를 중지했으며 선택된 서버가 추가되지 않았습니다.
1109 1211
1110```text theme={null}1212```text theme={null}
1111Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.1213Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.
1118* `claude_desktop_config.json`에서 서버 이름을 문자, 숫자, 하이픈 및 밑줄만 사용하도록 변경한 후 `claude mcp add-from-claude-desktop`을 다시 실행합니다.1220* `claude_desktop_config.json`에서 서버 이름을 문자, 숫자, 하이픈 및 밑줄만 사용하도록 변경한 후 `claude mcp add-from-claude-desktop`을 다시 실행합니다.
1119* 유효한 이름으로 `claude mcp add` 또는 `claude mcp add-json`을 사용하여 해당 서버를 직접 추가합니다. [Claude Desktop에서 MCP 서버 가져오기](/ko/mcp#import-mcp-servers-from-claude-desktop)를 참조하세요.1221* 유효한 이름으로 `claude mcp add` 또는 `claude mcp add-json`을 사용하여 해당 서버를 직접 추가합니다. [Claude Desktop에서 MCP 서버 가져오기](/ko/mcp#import-mcp-servers-from-claude-desktop)를 참조하세요.
1120 1222
1223<h3 id="mcp-permission-prompt-tool-not-found">
1224 MCP 권한 프롬프트 도구를 찾을 수 없습니다
1225</h3>
1226
1227[`--permission-prompt-tool`](/ko/cli-reference#cli-flags)에 전달한 도구는 실행이 처음으로 권한 결정이 필요할 때 연결된 MCP 도구 중에 없었습니다. 이는 서버가 연결되지 않았거나 연결된 서버가 해당 이름의 도구를 노출하지 않기 때문입니다. Claude Code는 여전히 프롬프트를 보냅니다. [비대화형](/ko/headless) 실행은 승인이 필요한 첫 번째 도구 호출에서 이 오류로 종료되고 종료 코드 1로 종료되므로 요청이 이루어졌음에도 불구하고 답변을 생성하지 않습니다. 첫 번째 프롬프트 전에 Claude Code는 [`MCP_TIMEOUT`](/ko/env-vars)으로 설정된 서버당 연결 타임아웃 30초까지 해당 서버가 연결될 때까지 기다립니다. {/* min-version: 2.1.206 */}v2.1.206 이전에는 시작 시 서버가 연결을 완료할 때까지 기다리지 않았으므로 느리게 시작되지만 정상인 서버도 이 오류를 생성했습니다.
1228
1229```text theme={null}
1230Error: MCP tool mcp__permissions__approve (passed via --permission-prompt-tool) not found. Available MCP tools: none
1231```
1232
1233`Available MCP tools:` 뒤의 목록은 대기가 끝났을 때 연결된 MCP 도구의 이름을 나타냅니다.
1234
1235**수행할 작업:**
1236
1237* 서버가 시작되고 연결 상태를 유지하는지 확인합니다. 동일한 디렉터리에서 `claude mcp list`를 실행하고 서버가 연결됨으로 나열되어 있는지 확인합니다.
1238* 도구 이름이 서버가 노출하는 `mcp__<server>__<tool>` 이름과 일치하는지 확인합니다.
1239* 서버를 시작하는 데 30초 이상이 필요한 경우 [`MCP_TIMEOUT`](/ko/env-vars)을 높입니다.
1240
1121<h2 id="plugin-errors">1241<h2 id="plugin-errors">
1122 플러그인 오류1242 플러그인 오류
1123</h2>1243</h2>
1128 마켓플레이스가 신뢰할 수 없는 소스에서 등록됨1248 마켓플레이스가 신뢰할 수 없는 소스에서 등록됨
1129</h3>1249</h3>
1130 1250
1131마켓플레이스가 [공식 Anthropic 마켓플레이스용으로 예약된](/ko/plugin-marketplaces#marketplace-schema) 이름으로 등록되어 있지만, 등록된 소스가 `anthropics` GitHub 저장소가 아닙니다. Claude Code는 마켓플레이스를 로드하거나 새로고침할 때마다 예약된 이름을 다시 확인하므로, 마켓플레이스와 여기서 설치된 플러그인이 로드되지 않습니다. v2.1.205 이전에는 마켓플레이스가 추가될 때만 이름이 확인되었으므로, 이름이 예약되기 전에 등록된 항목은 계속 로드되었습니다.1251마켓플레이스가 [공식 Anthropic 마켓플레이스용으로 예약된](/ko/plugin-marketplaces#marketplace-schema) 이름으로 등록되어 있지만, 등록된 소스가 `anthropics` GitHub 저장소가 아닙니다. Claude Code는 마켓플레이스를 로드하거나 새로 고칠 때마다 예약된 이름을 다시 확인하므로, 마켓플레이스와 여기서 설치된 플러그인이 로드되지 않습니다. v2.1.205 이전에는 마켓플레이스가 추가될 때만 이름이 확인되었으므로, 이름이 예약되기 전에 등록된 항목은 계속 로드되었습니다.
1132 1252
1133```text theme={null}1253```text theme={null}
1134Marketplace "claude-community" is registered from an untrusted source: The name 'claude-community' is reserved for official Anthropic marketplaces. Only repositories from 'github.com/anthropics/' can use this name. To fix it, remove the marketplace and re-add it from the official source.1254Marketplace "claude-community" is registered from an untrusted source: The name 'claude-community' is reserved for official Anthropic marketplaces. Only repositories from 'github.com/anthropics/' can use this name. To fix it, remove the marketplace and re-add it from the official source.
1135```1255```
1136 1256
1137**수행할 작업:**1257**해야 할 일:**
1138 1258
1139* `claude plugin marketplace remove <name>`을 실행한 다음, 공식 `github.com/anthropics` 저장소에서 마켓플레이스를 다시 추가합니다1259* `claude plugin marketplace remove <name>`을 실행한 다음 공식 `github.com/anthropics` 저장소에서 마켓플레이스를 다시 추가합니다
1140* 이름이 예약되기 전에 해당 이름을 사용한 타사 마켓플레이스를 게시한 경우, 이름을 바꾸고 사용자에게 소스에서 다시 추가하도록 요청합니다1260* 이름이 예약되기 전에 해당 이름을 사용한 타사 마켓플레이스를 게시한 경우, 이름을 바꾸고 사용자에게 소스에서 다시 추가하도록 요청합니다
1141* [마켓플레이스 스키마](/ko/plugin-marketplaces#marketplace-schema)에서 예약된 이름 목록을 참조합니다1261* [마켓플레이스 스키마](/ko/plugin-marketplaces#marketplace-schema)에서 예약된 이름 목록을 참조하십시오
1262
1263<h3 id="plugin-command-references-user-config">
1264 플러그인 명령이 셸 명령에서 user\_config를 참조함
1265</h3>
1266
1267플러그인 훅, [모니터](/ko/plugins-reference#monitors) 또는 MCP [`headersHelper`](/ko/mcp#use-dynamic-headers-for-custom-authentication) 명령이 `${user_config.KEY}` [플러그인 옵션](/ko/plugins-reference#user-configuration)을 참조하고, 대체된 문자열이 셸에 전달될 것입니다. `$(...)`, 백틱 또는 `;`을 포함하는 구성된 값은 여기서 코드로 실행될 수 있으므로, Claude Code는 값을 대체하는 대신 구성 요소 시작을 거부합니다. 확인은 명령 템플릿에서 실행되므로, 아직 값이 구성되지 않았을 때도 오류가 나타납니다. v2.1.207 이전에는 값이 셸 명령으로 대체되었습니다.
1268
1269표현은 옵션을 참조한 표면에 따라 다릅니다. 셸 형식 훅은 다음을 보고합니다:
1270
1271```text theme={null}
1272Hook from plugin formatter@acme-tools references ${user_config.*} in a shell-form command. The substituted value would be re-parsed by the shell. Use exec form instead — {"command": "<executable>", "args": ["${user_config.KEY}", ...]} — or read $CLAUDE_PLUGIN_OPTION_<KEY> from the hook's environment. Command: ./scripts/notify.sh ${user_config.webhook_url}
1273```
1274
1275모니터는 다음을 보고합니다:
1276
1277```text theme={null}
1278Monitor "deploy-status" from plugin deploy-tools references ${user_config.*} in its command. The substituted value would be passed to a shell. Monitor commands cannot safely reference ${user_config.*}; have the monitor script read the value from a config file or prompt instead.
1279```
1280
1281MCP `headersHelper`는 다음을 보고합니다:
1282
1283```text theme={null}
1284headersHelper for MCP server 'internal-api' references ${user_config.*}. The substituted value would be passed to a shell; read the value inside the helper script instead (e.g. from an env var set in the server's "env" block).
1285```
1286
1287**해야 할 일:**
1288
1289* 훅의 경우, `args` 배열을 추가하여 [exec 형식](/ko/hooks#exec-form-and-shell-form)으로 실행되도록 합니다. 여기서 각 `${user_config.KEY}`는 그 사이에 셸이 없는 하나의 인수가 됩니다. 또는 참조를 제거하고 스크립트 내에서 `$CLAUDE_PLUGIN_OPTION_<KEY>` 환경 변수를 읽습니다
1290* 모니터의 경우, 참조를 제거하고 모니터 스크립트가 구성 파일에서 값을 읽도록 합니다
1291* `headersHelper`의 경우, `${user_config.KEY}`를 셸 구문 분석이 되지 않는 서버의 `headers` 필드로 이동하거나, 헬퍼 스크립트 내에서 값을 읽습니다
1292
1293<h2 id="tool-errors">
1294 도구 오류
1295</h2>
1296
1297이러한 오류는 Claude의 기본 제공 도구가 입력을 거부할 때 발생합니다. Claude는 대부분의 도구 오류를 자동으로 수정합니다. 아래의 두 가지 오류는 사용자가 제어하는 서브에이전트 정의 또는 권한 규칙에서 비롯되므로 사용자의 변경이 필요합니다.
1298
1299<h3 id="agent-would-be-spawned-with-zero-tools">
1300 에이전트가 도구 없이 생성됨
1301</h3>
1302
1303[서브에이전트의 `tools` 목록](/ko/sub-agents#supported-frontmatter-fields)의 항목이 도구로 확인되지 않아 Claude Code가 작동할 수 없는 서브에이전트를 시작하는 대신 서브에이전트 시작을 거부합니다. 메시지는 항목을 확인되지 않은 이유별로 그룹화합니다: 인식되지 않은 도구, 서브에이전트에서 사용할 수 없는 도구, 또는 현재 세션의 도구와 일치하지 않는 인식된 도구입니다. `tools` 필드를 생략하면 이 거부가 트리거되지 않습니다. `mcp__github__*`와 같은 MCP 서버 패턴은 예외가 아닙니다: 해당 서버에서 연결된 도구가 없으면 패턴이 일치하지 않은 그룹에 있는 패턴으로 시작이 거부됩니다. v2.1.208 이전에는 서브에이전트가 도구 없이 시작되어 빈 결과 또는 혼란스러운 결과를 반환했습니다.
1304
1305```text theme={null}
1306Agent 'code-reviewer' would be spawned with zero tools — refusing. Its tools list resolved to nothing: unrecognized [Grpe]. Fix the agent's tools frontmatter or pass a different subagent_type.
1307```
1308
1309**수행할 작업:**
1310
1311* 오류가 명시한 각 항목을 [서브에이전트에서 사용 가능한 도구](/ko/sub-agents#available-tools)와 비교하여 수정합니다.
1312* 연결되지 않은 서버의 MCP 도구와 같이 세션에 없는 도구의 항목을 제거합니다.
1313* 서브에이전트에 부모가 가진 모든 도구를 제공하려면 도구를 나열하는 대신 `tools` 필드를 삭제합니다.
1314
1315<h3 id="file-is-covered-by-a-read-deny-rule">
1316 파일이 Read 거부 규칙으로 보호됨
1317</h3>
1318
1319Edit 도구가 [`Read` 거부 규칙](/ko/permissions#read-and-edit)과 일치하는 경로에서 호출되었습니다. 여기에는 해당 경로에서 새 파일을 만드는 것도 포함됩니다. 편집은 Claude가 다시 읽을 수 있어야 하는 콘텐츠를 다시 작성하므로 파일 액세스 전에 호출이 거부됩니다. 규칙은 Edit 도구만 차단합니다: Write와 NotebookEdit은 `Read` 거부 규칙의 영향을 받지 않습니다. v2.1.208 이전에는 `Edit` 거부 규칙만 편집을 차단했으며 `Read` 거부 규칙 단독으로는 차단하지 않았습니다.
1320
1321```text theme={null}
1322File is covered by a Read deny rule in your permission settings and cannot be edited.
1323```
1324
1325**수행할 작업:**
1326
1327* Claude가 파일을 편집할 수 있어야 하는 경우 `/permissions`의 `Read` 거부 규칙을 제거하거나 좁히거나 [설정](/ko/settings#permission-settings)에서 제거합니다.
1328* 파일이 그대로 유지되어야 하는 경우 규칙을 유지하고 Write와 NotebookEdit 도구도 차단되도록 동일한 경로에 대한 `Edit` 거부 규칙을 추가합니다.
1329
1330<h2 id="background-session-errors">
1331 백그라운드 세션 오류
1332</h2>
1333
1334[백그라운드 세션](/ko/agent-view)은 자체 대화형 터미널 없이 실행되므로 터미널이 필요한 명령은 다르게 작동합니다. 이러한 메시지는 백그라운드 세션의 기록, 에이전트 뷰 또는 연결 후에 나타납니다.
1335
1336<h3 id="commands-refused-in-a-background-session">
1337 백그라운드 세션에서 거부된 명령
1338</h3>
1339
1340대화형 대화 상자를 여는 명령은 백그라운드 세션에서 거부되며, 해당 위치에서 작동하는 양식의 이름을 지정하거나 일반 터미널에서 명령을 실행하도록 지시하는 메시지가 표시됩니다. `/install-github-app`, `/mcp` 설정 목록 및 MCP 서버 메뉴의 인증 작업은 모두 이러한 방식으로 거부됩니다. v2.1.208 이전에는 백그라운드 세션 내에서 대화 상자를 열었습니다.
1341{/* max-version: 2.1.208 */}v2.1.208에서만 `/model` 선택기도 백그라운드 세션에서 거부되었으며, `/upgrade`는 브라우저를 열지 않고 업그레이드 URL을 인쇄했습니다.
1342
1343표현은 거부된 명령의 이름을 지정합니다. `/mcp` 설정 목록은 다음을 보고합니다:
1344
1345```text theme={null}
1346Can't open MCP settings in a background session — use `/mcp enable|disable|reconnect <server>` to steer, or run /mcp from an interactive terminal to authenticate.
1347```
1348
1349**수행할 작업:**
1350
1351* `/mcp reconnect <server>`, `/mcp enable` 또는 `/mcp disable`과 같이 메시지에서 지정한 양식을 사용합니다
1352* 로그인 및 인증 흐름의 경우 터미널의 일반 `claude` 세션에서 명령을 실행합니다
1353
1354<h3 id="claude_code_process_wrapper-launcher-errors">
1355 CLAUDE\_CODE\_PROCESS\_WRAPPER 런처 오류
1356</h3>
1357
1358[`CLAUDE_CODE_PROCESS_WRAPPER`](/ko/corporate-launcher)가 설정되어 있고 해당 값을 사용할 수 없으므로 Claude Code는 런처 없이 실행하지 않고 영향을 받는 프로세스를 시작하기를 거부합니다. 구성 문제는 변수 이름으로 시작하고 이유를 명시하는 메시지로 보고됩니다. 예를 들어:
1359
1360```text theme={null}
1361CLAUDE_CODE_PROCESS_WRAPPER: launcher `/opt/corp/launcher` is not an executable regular file
1362```
1363
1364시작되었지만 Claude Code로 자신을 대체하지 않고 종료되는 런처는 시작하려던 세션을 실패하게 하며, 에이전트 뷰의 세션 행은 런처가 `must exec, not daemonize`를 수행해야 함을 보고하고 런처가 인쇄한 모든 항목을 따릅니다. 런처로 인해 시작할 수 없거나 백그라운드 서비스에 도달할 수 없는 세션은 런처 문제를 `Couldn't reach the background service (...)`의 이유로 보고합니다.
1365
1366**수행할 작업:**
1367
1368* 변수를 `exec "$@"`를 호출하여 끝나는 실행 파일의 절대 경로로 설정합니다. 전체 계약은 [런처 계약](/ko/corporate-launcher#the-launcher-contract)을 참조하세요
1369* `/status`를 확인합니다. 이는 Self-exec 항목에서 해결된 시작 명령을 표시하고 실행 중인 백그라운드 서비스가 일치하지 않을 때 경고하거나, 셸에서 `claude daemon status`를 실행합니다
1370* [설정](/ko/corporate-launcher#set-up-the-launcher)의 `env` 블록에서 값을 수정한 후 `claude daemon stop --any`로 백그라운드 서비스를 다시 시작하여 다음 디스패치가 래핑된 서비스를 시작하도록 합니다
1142 1371
1143<h2 id="configuration-warnings">1372<h2 id="configuration-warnings">
1144 구성 경고1373 구성 경고
1145</h2>1374</h2>
1146 1375
1147Claude Code는 이러한 메시지를 시작 시 대화에 오류로 표시하지 않고 stderr에 기록합니다. 이는 읽었지만 적용하지 않은 구성을 보고합니다.1376Claude Code는 대화에서 오류를 표시하는 대신 시작 시 이러한 메시지를 stderr에 작성합니다. 읽었지만 적용하지 않은 구성을 보고합니다.
1148 1377
1149<h3 id="workspace-has-not-been-trusted">1378<h3 id="workspace-has-not-been-trusted">
1150 작업 공간이 신뢰되지 않음1379 작업 공간이 신뢰되지 않음
1158 1387
1159**수행할 작업:**1388**수행할 작업:**
1160 1389
1161* 디렉터리에서 `claude`를 실행하고 신뢰 대화를 수락합니다. {/* min-version: 2.1.200 */}부모 디렉터리가 이미 신뢰된 경우에도 대화가 나타나며, 보류 중인 규칙을 나열하고 거절하여 규칙 없이 계속 작업할 수 있습니다. v2.1.200 이전에는 해당 상황에서 대화가 나타나지 않았으므로 이 단계를 완료할 수 없었습니다.1390* 디렉터리에서 `claude`를 실행하고 신뢰 대화를 수락합니다. {/* min-version: 2.1.200 */}부모 디렉터리가 이미 신뢰된 경우에도 대화가 나타나며, 보류 중인 규칙을 나열하고 거절하고 규칙 없이 계속 작업할 수 있습니다. v2.1.200 이전에는 해당 상황에서 대화가 나타나지 않았으므로 이 단계를 완료할 수 없었습니다.
1162* `-p`를 사용한 [비대화형 모드](/ko/headless)에서는 대화가 표시되지 않습니다. 메시지가 출력하는 정확한 `projects` 키를 사용하여 `~/.claude.json`에서 `hasTrustDialogAccepted` 항목을 설정합니다.1391* `-p`를 사용한 [비대화형 모드](/ko/headless)에서는 대화가 표시되지 않습니다. 메시지가 출력하는 정확한 `projects` 키를 사용하여 `~/.claude.json`에서 `hasTrustDialogAccepted` 항목을 설정합니다.
1163* {/* min-version: 2.1.200 */}메시지에 `.claude/settings.local.json`이 명시되어 있고 git 저장소 외부 또는 홈 디렉터리에서 Claude Code를 시작한 경우 v2.1.200 이상으로 업데이트합니다. 버전 2.1.196부터 2.1.199까지는 해당 작업 공간에서 자신의 `.claude/settings.local.json`을 저장소 제공으로 취급했습니다. [프로젝트 allow 규칙 및 작업 공간 신뢰](/ko/permissions#project-allow-rules-and-workspace-trust)를 참조하세요.1392* {/* min-version: 2.1.200 */}메시지가 `.claude/settings.local.json`을 지정하고 git 저장소 외부 또는 홈 디렉터리에서 Claude Code를 시작한 경우 v2.1.200 이상으로 업데이트합니다. 버전 2.1.196부터 2.1.199까지는 해당 작업 공간에서 자신의 `.claude/settings.local.json`을 저장소 제공으로 취급했습니다. {/* min-version: 2.1.207 */}v2.1.207 이상에서는 git 저장소 외부에서 폴더를 신뢰하지 않은 경우 업데이트만으로는 충분하지 않습니다. 폴더가 저장소 내부에 있지 않은지 확인하면 git이 실행되고, Claude Code는 신뢰 대화를 수락한 후에만 해당 확인을 실행하므로 첫 번째 단계를 사용합니다. 홈 디렉터리 및 기타 [구성 홈](/ko/permissions#project-allow-rules-and-workspace-trust)은 제외되며 대화를 기다리지 않습니다. [프로젝트 allow 규칙 및 작업 공간 신뢰](/ko/permissions#project-allow-rules-and-workspace-trust)를 참조하세요.
1164 1393
1165<h2 id="responses-seem-lower-quality-than-usual">1394<h2 id="responses-seem-lower-quality-than-usual">
1166 응답 품질이 평소보다 낮아 보입니다1395 응답 품질이 평소보다 낮아 보입니다
1167</h2>1396</h2>
1168 1397
1169Claude의 답변이 예상보다 능력이 떨어져 보이지만 오류가 표시되지 않는 경우, 원인은 일반적으로 모델 자체가 아니라 대화 상태입니다. Claude Code는 자동으로 모델 버전을 변경하지 않습니다. 다음 세 가지 특정 경우에만 폴백 모델로 전환할 수 있습니다.1398Claude의 답변이 예상보다 덜 능력 있어 보이지만 오류가 표시되지 않는 경우, 원인은 일반적으로 모델 자체가 아니라 대화 상태입니다. Claude Code는 모델 버전을 자동으로 변경하지 않습니다. 세 가지 특정 경우에만 폴백 모델로 전환할 수 있습니다.
1170 1399
1171* 구성된 [`--fallback-model`](/ko/cli-reference#cli-flags)은 가용성 오류 후 해당 턴에만 인수를 받으며, 트랜스크립트에 공지가 표시됩니다.1400* 구성된 [`--fallback-model`](/ko/cli-reference#cli-flags)은 가용성 오류 후 해당 턴에만 인수를 받으며, 트랜스크립트에 공지가 표시됩니다.
1172* Amazon Bedrock 또는 Google Cloud의 Agent Platform 시작 확인에서 기본 모델을 사용할 수 없음을 발견합니다.1401* Amazon Bedrock 또는 Google Cloud의 Agent Platform 시작 확인에서 기본 모델을 사용할 수 없음을 발견합니다.
1173* [자동 모델 폴백](/ko/model-config#automatic-model-fallback)이 Fable 5에서 세션을 기본 Opus 모델로 이동하고 트랜스크립트에 공지를 표시합니다.1402* [자동 모델 폴백](/ko/model-config#automatic-model-fallback)은 Fable 5에서 세션을 기본 Opus 모델로 이동하고 트랜스크립트에 공지를 표시합니다.
1174 1403
1175아래의 모델 선택 확인은 두 번째 및 세 번째 경우를 포착합니다. 첫 번째는 `/model` 변경이 아닌 트랜스크립트 공지로 나타납니다. [모델 구성](/ko/model-config)에서 각 폴백이 적용되는 시기를 설명합니다.1404아래의 모델 선택 확인은 두 번째 및 세 번째 경우를 포착합니다. 첫 번째는 `/model` 변경이 아니라 트랜스크립트 공지로 나타납니다. [모델 구성](/ko/model-config)은 각 폴백이 적용되는 시기를 설명합니다.
1176 1405
1177먼저 다음을 확인하십시오.1406먼저 다음을 확인하십시오.
1178 1407
1179* **모델 선택**: `/model`을 실행하여 예상하는 모델에 있는지 확인합니다. 이전 `/model` 선택 또는 `ANTHROPIC_MODEL` 환경 변수로 인해 의도한 것보다 작은 모델에 있을 수 있습니다.1408* **모델 선택**: `/model`을 실행하여 예상하는 모델에 있는지 확인합니다. 이전 `/model` 선택 또는 `ANTHROPIC_MODEL` 환경 변수로 인해 의도한 것보다 작은 모델에 있을 수 있습니다.
1180* **노력 수준**: `/effort`를 실행하여 현재 추론 수준을 확인하고 어려운 디버깅 또는 설계 작업을 위해 수준을 높입니다. 기본값은 모델에 따라 다르므로 최대값 이하에 있다고 가정하기 전에 확인하십시오. 모델별 기본값 및 `ultrathink` 단축키는 [노력 수준 조정](/ko/model-config#adjust-effort-level)을 참조하십시오.1409* **노력 수준**: `/effort`를 실행하여 현재 추론 수준을 확인하고 어려운 디버깅 또는 설계 작업을 위해 높입니다. 기본값은 모델에 따라 다르므로 최대값 이하에 있다고 가정하기 전에 확인하십시오. 모델별 기본값 및 `ultrathink` 바로 가기는 [노력 수준 조정](/ko/model-config#adjust-effort-level)을 참조하십시오.
1181* **컨텍스트 압력**: `/context`를 실행하여 윈도우가 얼마나 찼는지 확인합니다. 용량에 가까우면 자연스러운 지점에서 `/compact`를 실행하거나 `/clear`를 실행하여 새로 시작합니다. [컨텍스트 윈도우 탐색](/ko/context-window)에서 자동 압축이 이전 턴에 어떻게 영향을 미치는지 확인하십시오.1410* **컨텍스트 압력**: `/context`를 실행하여 윈도우가 얼마나 찼는지 확인합니다. 용량에 가까우면 자연스러운 지점에서 `/compact`를 실행하거나 `/clear`를 실행하여 새로 시작합니다. [컨텍스트 윈도우 탐색](/ko/context-window)에서 자동 압축이 이전 턴에 어떻게 영향을 미치는지 확인하십시오.
1182* **오래된 지침**: 크거나 오래된 `CLAUDE.md` 파일 및 MCP 도구 정의는 컨텍스트를 소비하고 응답을 조종할 수 있습니다. {/* min-version: 2.1.205 */}`/doctor` 점검은 과도한 메모리 파일 및 사용하지 않는 확장 프로그램에 플래그를 지정하며, `/context`는 MCP 도구 토큰 사용량을 표시합니다. v2.1.205 이전에는 `/doctor`가 과도한 메모리 파일 및 서브에이전트 정의에 플래그를 지정하는 진단 화면을 열었습니다.1411* **오래된 지침**: 크거나 오래된 `CLAUDE.md` 파일 및 MCP 도구 정의는 컨텍스트를 소비하고 응답을 조종할 수 있습니다. {/* min-version: 2.1.205 */}`/doctor` 점검은 과도하게 큰 메모리 파일 및 사용하지 않는 확장을 표시하며, `/context`는 MCP 도구 토큰 사용을 표시합니다. v2.1.205 이전에는 `/doctor`가 과도하게 큰 메모리 파일 및 서브에이전트 정의를 표시하는 진단 화면을 열었습니다.
1183 1412
1184응답이 잘못되면 수정으로 회신하는 것보다 되감기가 일반적으로 더 잘 작동합니다. Esc를 두 번 누르거나 `/rewind`를 실행하여 잘못된 턴 이전으로 돌아간 다음 더 구체적인 프롬프트로 다시 표현합니다. 스레드 내에서 수정하면 잘못된 시도가 컨텍스트에 남아 있어 나중의 답변을 고정시킬 수 있습니다. [체크포인팅](/ko/checkpointing)을 참조하십시오.1413응답이 잘못되면 수정으로 회신하는 것보다 보통 되감기가 더 잘 작동합니다. Esc를 두 번 누르거나 `/rewind`를 실행하여 잘못된 턴 이전으로 돌아간 다음 더 구체적인 프롬프트로 다시 표현합니다. 스레드 내에서 수정하면 잘못된 시도가 컨텍스트에 남아 있어 나중의 답변을 고정할 수 있습니다. [체크포인팅](/ko/checkpointing)을 참조하십시오.
1185 1414
1186위의 항목을 확인한 후에도 품질이 여전히 좋지 않으면 `/feedback`을 실행하고 예상한 것과 실제로 받은 것을 설명합니다. 이 방식으로 제출된 피드백에는 대화 트랜스크립트가 포함되어 있으며, 이는 Anthropic이 실제 회귀를 진단하는 가장 빠른 방법입니다. 환경에서 `/feedback`을 사용할 수 없는 경우 [오류 보고](#report-an-error)를 참조하십시오.1415위의 항목을 확인한 후에도 품질이 여전히 좋지 않으면 `/feedback`을 실행하고 예상한 것과 얻은 것을 설명합니다. 이 방식으로 제출된 피드백에는 대화 트랜스크립트가 포함되며, 이는 Anthropic이 실제 회귀를 진단하는 가장 빠른 방법입니다. 환경에서 `/feedback`을 사용할 수 없는 경우 [오류 보고](#report-an-error)를 참조하십시오.
1187 1416
1188{/* min-version: 2.1.201 */}Sonnet 5가 요청을 거부하고 Claude Code v2.1.200 이전 버전에서 의심되는 프롬프트 주입을 인용하는 경우 `claude update`를 실행하여 v2.1.201 수정을 선택합니다.1417Claude가 의심되는 프롬프트 주입에 대해 경고하거나 의심되는 주입으로 인해 요청을 거부하고, 경고가 명명하는 텍스트가 파일 또는 웹 콘텐츠가 아니라 Claude Code가 대화에 자동으로 추가하는 컨텍스트인 경우 `claude update`를 실행하고 다시 시도합니다. 업데이트 후 경고가 반복되면 플래그된 콘텐츠를 프롬프트에 다시 붙여넣는 대신 [보고](#report-an-error)하십시오. {/* min-version: 2.1.201 */}v2.1.201 이전에는 Sonnet 5가 같은 방식으로 일부 요청을 거부했습니다.
1189 1418
1190<h2 id="report-an-error">1419<h2 id="report-an-error">
1191 오류 보고1420 오류 보고
1194이 페이지에서 다루지 않는 구성 요소의 오류는 관련 가이드를 참조하십시오:1423이 페이지에서 다루지 않는 구성 요소의 오류는 관련 가이드를 참조하십시오:
1195 1424
1196* MCP 서버 연결 또는 인증 실패: [MCP](/ko/mcp)1425* MCP 서버 연결 또는 인증 실패: [MCP](/ko/mcp)
1197* 훅 스크립트 실패 또는 도구 차단: [Debug hooks](/ko/hooks#debug-hooks)1426* 훅 스크립트 실패 또는 도구 차단: [훅 디버깅](/ko/hooks#debug-hooks)
1198* 설치 중 권한 거부 또는 파일 시스템 오류: [Troubleshoot installation and login](/ko/troubleshoot-install)1427* 설치 중 권한 거부 또는 파일 시스템 오류: [설치 및 로그인 문제 해결](/ko/troubleshoot-install)
1199 1428
1200오류가 여기에 나열되지 않았거나 제안된 해결 방법이 도움이 되지 않는 경우:1429오류가 여기에 나열되지 않았거나 제안된 해결 방법이 도움이 되지 않는 경우:
1201 1430
1202* Claude Code 내에서 `/feedback`을 실행하여 기록 및 설명을 Anthropic에 전송하십시오. 이 명령은 미리 작성된 GitHub 이슈를 열 수 있는 옵션도 제공합니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 및 기타 타사 제공자에서는 `/feedback`이 Anthropic 계정 담당자에게 보낼 수 있는 로컬 아카이브를 저장합니다.1431* Claude Code 내에서 `/feedback`을 실행하여 기록 및 설명을 Anthropic에 전송하십시오. 이 명령은 미리 작성된 GitHub 이슈를 열 수 있는 옵션도 제공합니다. Anthropic에 전송하려면 [인증](/ko/authentication)이 필요합니다. Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry 및 기타 타사 제공자에서 또는 Anthropic 자격 증명이 구성되지 않은 경우, `/feedback`은 대신 Anthropic 계정 담당자에게 보낼 수 있는 로컬 아카이브를 저장합니다.
1203* 셸에서 `claude doctor`를 실행하여 설치의 읽기 전용 진단을 수행하거나, Claude Code 내에서 `/doctor` 점검을 실행하여 설정 문제를 찾고 해결하십시오1432* 셸에서 `claude doctor`를 실행하여 설치의 읽기 전용 진단을 수행하거나, Claude Code 내에서 `/doctor` 점검을 실행하여 설정 문제를 찾고 수정하십시오
1204* [status.claude.com](https://status.claude.com)에서 활성 인시던트를 확인하십시오1433* [status.claude.com](https://status.claude.com)에서 활성 인시던트를 확인하십시오
1205* GitHub의 [기존 이슈](https://github.com/anthropics/claude-code/issues)를 검색하십시오1434* GitHub의 [기존 이슈](https://github.com/anthropics/claude-code/issues)를 검색하십시오
