122| `A request to MCP server "<name>" was sent without your stored credentials` | [인증](#couldnt-read-the-stored-credentials-for-mcp-server) |122| `A request to MCP server "<name>" was sent without your stored credentials` | [인증](#couldnt-read-the-stored-credentials-for-mcp-server) |
123| `This server's URL is missing or not a valid URL, so sign-in can't start` | [인증](#mcp-server-url-is-missing-or-not-a-valid-url) |123| `This server's URL is missing or not a valid URL, so sign-in can't start` | [인증](#mcp-server-url-is-missing-or-not-a-valid-url) |
124| `Issuer mismatch in authorization response (RFC 9207)` | [인증](#issuer-mismatch-in-authorization-response) |124| `Issuer mismatch in authorization response (RFC 9207)` | [인증](#issuer-mismatch-in-authorization-response) |
125| `Stopped an OAuth request` | [인증](#stopped-an-oauth-request) |
125| `Refusing to send credentials to non-https token endpoint` / `<short-name> from the MCP SDK for <server-url>` | [인증](#refusing-to-send-credentials-to-non-https-token-endpoint) |126| `Refusing to send credentials to non-https token endpoint` / `<short-name> from the MCP SDK for <server-url>` | [인증](#refusing-to-send-credentials-to-non-https-token-endpoint) |
126| `Cloud gateway session expired — run /login to reconnect.` | [인증](#cloud-gateway-session-expired) |127| `Cloud gateway session expired — run /login to reconnect.` | [인증](#cloud-gateway-session-expired) |
127| `Cloud gateway <url> no longer accepts this session` | [인증](#cloud-gateway-session-expired) |128| `Cloud gateway <url> no longer accepts this session` | [인증](#cloud-gateway-session-expired) |
251| `Ultrareview did not start` | [명령줄 오류](#ultrareview-did-not-start) |252| `Ultrareview did not start` | [명령줄 오류](#ultrareview-did-not-start) |
252| `Remote Control did not start: "<question>" got no answer` | [명령줄 오류](#remote-control-did-not-start-got-no-answer) |253| `Remote Control did not start: "<question>" got no answer` | [명령줄 오류](#remote-control-did-not-start-got-no-answer) |
253| `` `<flag>` before `remote-control` is not carried over to the sessions Remote Control starts `` | [명령줄 오류](#not-carried-over-to-the-sessions-remote-control-starts) |254| `` `<flag>` before `remote-control` is not carried over to the sessions Remote Control starts `` | [명령줄 오류](#not-carried-over-to-the-sessions-remote-control-starts) |
255| `Remote Control did not start, because sessions would skip part or all of the --settings file` | [명령줄 오류](#remote-control-did-not-start-because-of-the-settings-file) |
256| `The settings file <file> has changed since Remote Control started, so this session did not start` | [명령줄 오류](#settings-file-changed-since-remote-control-started) |
254| `--sandbox is not supported by claude remote-control` / `--no-sandbox is not supported by claude remote-control` | [명령줄 오류](#sandbox-is-not-supported-by-claude-remote-control) |257| `--sandbox is not supported by claude remote-control` / `--no-sandbox is not supported by claude remote-control` | [명령줄 오류](#sandbox-is-not-supported-by-claude-remote-control) |
255| `` `claude import` is not yet available in this build `` | [명령줄 오류](#claude-import-is-not-yet-available-in-this-build) |258| `` `claude import` is not yet available in this build `` | [명령줄 오류](#claude-import-is-not-yet-available-in-this-build) |
256| `Could not read Claude Code config` | [명령줄 오류](#could-not-read-claude-code-config) |259| `Could not read Claude Code config` | [명령줄 오류](#could-not-read-claude-code-config) |
825동일한 Claude 응답의 이후 호출도 다음 사유로 거부될 수 있습니다:828동일한 Claude 응답의 이후 호출도 다음 사유로 거부될 수 있습니다:
826 829
827```text theme={null}830```text theme={null}
828another call in this response was changed by a hook after auto mode reviewed it, or could not be confirmed unchanged831another call in this response was changed after auto mode reviewed it, or could not be confirmed unchanged
829```832```
830 833
831그러면 Claude는 거부된 각 호출을 다시 발급하여 서버가 검토하도록 할 수 있습니다. 권한 프롬프트가 열리면 응답합니다. Claude가 응답에서 자동 모드가 호출을 검사할 수 없었다고 말하지 않는 한 다른 작업은 필요하지 않습니다. 그런 경우 변경을 중지하거나 호출을 직접 승인한 다음 Claude에게 호출을 다시 시도하도록 요청합니다:834그러면 Claude는 거부된 각 호출을 다시 발급하여 서버가 검토하도록 할 수 있습니다. 권한 프롬프트가 열리면 응답합니다. Claude가 응답에서 자동 모드가 호출을 검사할 수 없었다고 말하지 않는 한 다른 작업은 필요하지 않습니다. 그런 경우 변경을 중지하거나 호출을 직접 승인한 다음 Claude에게 호출을 다시 시도하도록 요청합니다:
1822 1825
1823v2.1.232 이전에는 Claude Code가 점진적 출시 대상이거나 `MCP_SDK_GENERATION=v2`를 설정한 경우에만 v2 런타임을 사용했습니다.1826v2.1.232 이전에는 Claude Code가 점진적 출시 대상이거나 `MCP_SDK_GENERATION=v2`를 설정한 경우에만 v2 런타임을 사용했습니다.
1824 1827
1828### Stopped an OAuth request
1829
1830이 메시지는 OAuth 엔드포인트가 리디렉션했기 때문에 Claude Code가 [MCP 서버에 대한 OAuth 요청](https://code.claude.com/docs/ko/mcp.md#authenticate-with-remote-mcp-servers)을 중단했음을 의미합니다. 메시지의 두 가지 형태 모두에서 첫 번째 주소가 리디렉션을 보낸 주소입니다.
1831
1832```text theme={null}
1833Stopped an OAuth request, which can hold secrets: https://auth.example.com redirected it to https://other.example.com. Ask the owner of https://auth.example.com to remove that redirect.
1834Stopped an OAuth request: https://auth.example.com redirected it more than 5 times. Ask the owner of https://auth.example.com to fix those redirects.
1835```
1836
1837**해결 방법:**
1838
1839* MCP 서버 운영자 등 첫 번째 주소를 운영하는 사람에게 리디렉션을 제거하거나 수정하도록 요청합니다. 그런 다음 `/mcp`에서 다시 시도합니다.
1840
1825### HTTPS가 아닌 토큰 엔드포인트로 자격 증명 전송 거부1841### HTTPS가 아닌 토큰 엔드포인트로 자격 증명 전송 거부
1826 1842
1827[v2 런타임](https://code.claude.com/docs/ko/mcp.md#mcp-client-runtimes)에서 Claude Code는 HTTPS로 제공되거나 `localhost`, `127.0.0.1`, `::1`에 있는 토큰 엔드포인트에만 [MCP OAuth](https://code.claude.com/docs/ko/mcp.md#authenticate-with-remote-mcp-servers) 토큰 요청을 보냅니다. 이 메시지는 서버의 토큰 엔드포인트가 둘 다 해당하지 않아 Claude Code가 요청을 보내기 전에 중단했다는 뜻입니다. 이는 브라우저 로그인 이후에 발생하므로 브라우저 단계는 먼저 성공하며, Claude Code가 서버의 토큰을 갱신할 때마다 다시 발생합니다.1843[v2 런타임](https://code.claude.com/docs/ko/mcp.md#mcp-client-runtimes)에서 Claude Code는 HTTPS로 제공되거나 `localhost`, `127.0.0.1`, `::1`에 있는 토큰 엔드포인트에만 [MCP OAuth](https://code.claude.com/docs/ko/mcp.md#authenticate-with-remote-mcp-servers) 토큰 요청을 보냅니다. 이 메시지는 서버의 토큰 엔드포인트가 둘 다 해당하지 않아 Claude Code가 요청을 보내기 전에 중단했다는 뜻입니다. 이는 브라우저 로그인 이후에 발생하므로 브라우저 단계는 먼저 성공하며, Claude Code가 서버의 토큰을 갱신할 때마다 다시 발생합니다.
2207 2223
2208### 클라우드 세션에서 호스트가 허용되지 않음2224### 클라우드 세션에서 호스트가 허용되지 않음
2209 2225
2210클라우드 세션 또는 클라우드 예약 작업의 아웃바운드 HTTP 요청이 환경의 네트워크 정책에 의해 차단되었습니다.2226클라우드 세션 또는 클라우드 예약 작업에서 `403` 또는 `ENOTFOUND`와 같은 DNS 오류는 요청한 호스트가 [클라우드 환경의 허용 목록](https://code.claude.com/docs/ko/cloud-environments.md#access-levels)에 없음을 의미할 수 있습니다. 확인하려면 해당 목록과 호스트를 대조합니다. 이 헤더가 있는 `403`은 차단을 확인해 주지만, 차단된 모든 요청의 `403`에 이 헤더가 있는 것은 아닙니다:
2211 2227
2212```text theme={null}2228```text theme={null}
2213HTTP 4032229HTTP 403
2393 2409
2394## 요청 오류2410## 요청 오류
2395 2411
2396이 오류들은 요청의 내용과 관련이 있습니다. 대부분은 API가 요청을 거부한 후 API에서 반환되며, 일부는 요청이 전송되기 전에 Claude Code가 로컬에서 생성합니다.2412이 오류는 요청 내용과 관련됩니다. 대부분은 API가 요청을 거부한 후 API에서 반환되며, 일부는 요청이 전송되기 전에 Claude Code가 로컬에서 생성합니다.
2397 2413
2398### Prompt is too long2414### Prompt is too long
2399 2415
2400대화와 첨부 파일을 합친 크기가 모델의 컨텍스트 윈도우를 초과했습니다.2416대화와 첨부 파일을 합한 크기가 모델의 컨텍스트 윈도우를 초과합니다.
2401 2417
2402```text theme={null}2418```text theme={null}
2403Prompt is too long2419Prompt is too long
2404```2420```
2405 2421
2406대화형 세션에서 Claude Code는 이 오류를 다음과 같이 표시합니다.2422대화형 세션에서 Claude Code는 이 오류를 다음과 같이 표시합니다:
2407 2423
2408```text theme={null}2424```text theme={null}
2409Context limit reached · /compact or /clear to continue2425Context limit reached · /compact or /clear to continue
2410```2426```
2411 2427
2412[`DISABLE_COMPACT`](https://code.claude.com/docs/ko/env-vars)가 설정되어 있으면 이 줄에는 `/clear`만 표시됩니다. 아래의 압축 실패 형식과 같이 더 긴 형식의 오류는 `Prompt is too long ·` 문구를 유지합니다. `-p` 출력과 트랜스크립트에서는 텍스트가 `Prompt is too long`으로 유지됩니다.2428[`DISABLE_COMPACT`](https://code.claude.com/docs/ko/env-vars)가 설정되어 있으면 이 줄에는 `/clear`만 표시됩니다. 아래의 압축 실패 형식과 같은 더 긴 형식의 오류는 `Prompt is too long ·` 문구를 유지합니다. `-p` 출력과 트랜스크립트에서는 텍스트가 `Prompt is too long`으로 유지됩니다.
2413 2429
2414[사용자 설정](https://code.claude.com/docs/ko/settings-reference.md#autocompactenabled)에서 자동 압축을 끈 경우, 이 줄에 그 사실도 함께 표시됩니다.2430[사용자 설정](https://code.claude.com/docs/ko/settings-reference.md#autocompactenabled)에서 자동 압축을 끈 경우 이 줄에 해당 내용도 함께 표시됩니다:
2415 2431
2416```text theme={null}2432```text theme={null}
2417Context limit reached · /compact or /clear to continue · auto-compact is off · /config to turn it on2433Context limit reached · /compact or /clear to continue · auto-compact is off · /config to turn it on
2418```2434```
2419 2435
2420`/config`의 **Auto-compact** 토글은 사용자 설정에 `autoCompactEnabled`를 기록합니다. 이 힌트는 `/config` 변경이 실제로 적용될 때만 나타납니다. 예를 들어 [`DISABLE_AUTO_COMPACT`](https://code.claude.com/docs/ko/env-vars) 또는 [`DISABLE_COMPACT`](https://code.claude.com/docs/ko/env-vars)로 자동 압축을 끈 경우에는 나타나지 않습니다. 프로젝트 설정이나 관리형 설정처럼 우선순위가 더 높은 범위에서 `autoCompactEnabled`를 `false`로 설정한 경우에도 나타나지 않습니다. v2.1.235 이전에는 이 줄에 자동 압축 힌트가 포함되지 않았습니다.2436`/config`의 **Auto-compact** 토글은 사용자 설정에 `autoCompactEnabled`를 기록합니다. 이 힌트는 `/config` 변경이 실제로 적용될 수 있는 경우에만 표시됩니다. 예를 들어 [`DISABLE_AUTO_COMPACT`](https://code.claude.com/docs/ko/env-vars) 또는 [`DISABLE_COMPACT`](https://code.claude.com/docs/ko/env-vars)로 자동 압축을 끈 경우에는 표시되지 않습니다. 또한 프로젝트 설정이나 관리형 설정처럼 우선순위가 더 높은 범위에서 `autoCompactEnabled`를 `false`로 설정한 경우에도 표시되지 않습니다. v2.1.235 이전에는 이 줄에 자동 압축 힌트가 없었습니다.
2421 2437
2422Amazon Bedrock은 이 상태를 `Input is too long for requested model.`로 보고하며, Claude Code는 이를 동일한 방식으로 처리합니다. v2.1.217 이전에는 Claude Code가 Bedrock의 문구를 인식하지 못했기 때문에 자동 압축이 이 오류에서 트리거되지 않았고 `/compact`도 같은 오류로 실패했습니다.2438Amazon Bedrock은 이 상태를 `Input is too long for requested model.`로 보고하며, Claude Code는 이를 동일하게 처리합니다. v2.1.217 이전에는 Claude Code가 Bedrock의 문구를 인식하지 못해 자동 압축이 트리거되지 않았고 `/compact`도 같은 오류로 실패했습니다.
2423 2439
2424[Claude apps gateway](https://code.claude.com/docs/ko/claude-apps-gateway-config.md#upstream-error-messages)는 클라우드 업스트림이 제공업체 고유의 오류 형식으로 요청을 거부할 때 이 상태를 `capability_rejected: prompt_too_long`으로 보고합니다. Claude Code는 이 토큰을 `Prompt is too long`과 동일하게 처리합니다. v2.1.228 이전에는 Claude Code가 이 토큰을 인식하지 못했기 때문에 자동 압축이 트리거되지 않았습니다.2440[Claude apps gateway](https://code.claude.com/docs/ko/claude-apps-gateway-config.md#upstream-error-messages)는 클라우드 업스트림이 제공업체 고유의 오류 형식으로 요청을 거부하면 이 상태를 `capability_rejected: prompt_too_long`으로 보고합니다. Claude Code는 이 토큰을 `Prompt is too long`과 동일하게 처리합니다. v2.1.228 이전에는 Claude Code가 이 토큰을 인식하지 못해 자동 압축이 트리거되지 않았습니다.
2425 2441
2426이번 턴에 자동 압축이 실행되었으나 사용할 수 없는 모델이나 인증 실패 같은 근본 오류로 실패한 경우, 메시지는 구분 기호 뒤에 해당 오류를 표시합니다.2442이번 턴에서 자동 압축이 실행되었지만 모델을 사용할 수 없거나 인증에 실패하는 등 근본 오류로 인해 실패한 경우, 메시지의 구분 기호 뒤에 해당 오류가 표시됩니다:
2427 2443
2428```text theme={null}2444```text theme={null}
2429Prompt is too long · automatic compaction failed: <the underlying error>2445Prompt is too long · automatic compaction failed: <the underlying error>
2430```2446```
2431 2447
2432표시된 오류를 먼저 해결하십시오. 해결하기 전까지 `/compact`도 같은 오류로 실패합니다. v2.1.229 이전에는 자동 압축이 실패하면 원인 없이 `Prompt is too long`만 표시되었습니다.2448표시된 오류를 먼저 해결하세요. 해결하기 전까지는 `/compact`도 같은 오류로 실패합니다. v2.1.229 이전에는 자동 압축이 실패해도 원인 없이 `Prompt is too long`만 표시되었습니다.
2433 2449
2434이 오류에서 자동 압축이 실행되면 일반적으로 가장 오래된 대화 교환을 요약하고 최신 교환은 유지합니다. 최후의 수단으로 Claude Code는 다르게 요약합니다.2450이 오류에서 자동 압축이 실행되면 일반적으로 가장 오래된 대화 교환을 요약하고 최신 교환은 유지합니다. 최후의 수단으로 Claude Code는 다른 방식으로 요약합니다:
2435 2451
2436* 온전한 교환을 하나도 요약할 수 없는 경우, Claude Code는 최신 프롬프트를 그대로 유지하고 그 이전의 모든 내용을 요약합니다.2452* 전체 교환을 하나도 요약할 수 없는 경우 Claude Code는 최신 프롬프트를 그대로 유지하고 그 이전의 모든 내용을 요약합니다.
2437* 이 경우 대화가 사용자의 프롬프트로 끝나지 않으면, Claude Code는 대신 전체 대화를 요약합니다.2453* 이 경우 대화가 사용자의 프롬프트로 끝나지 않으면 Claude Code는 대신 대화 전체를 요약합니다.
2438 2454
2439이어서 유지할 내용에 모델 응답이 없고 사용자가 작성한 텍스트가 약 1,000토큰 미만인 경우(예: 너무 큰 붙여넣기 이후 보낸 짧은 재시도), Claude Code는 이 복구를 건너뜁니다. 새로 시작하려면 `/clear`를 실행하십시오. v2.1.269 이전에는 온전한 교환을 요약할 수 없을 때마다 압축이 실패했기 때문에, 그런 상태의 세션은 매 턴마다 이 오류가 다시 발생했습니다.2455Claude Code가 이어서 가져갈 내용에 모델 응답이 없고 사용자가 직접 작성한 텍스트가 약 1,000 토큰 미만인 경우(예: 지나치게 큰 내용을 붙여넣은 후 보낸 짧은 재시도), Claude Code는 이 복구를 건너뜁니다. `/clear`를 실행하여 새로 시작하세요. v2.1.269 이전에는 전체 교환을 요약할 수 없을 때마다 압축이 실패했기 때문에, 이 상태의 세션에서는 매 턴마다 이 오류가 다시 발생했습니다.
2440 2456
2441교환이 하나뿐인 대화에는 요약할 이전 턴이 없습니다. 이런 대화에서 자동 압축이 실행될 상황이 되면, Claude Code는 시도를 건너뛰고 대신 무엇이 요청을 채우고 있는지 설명합니다. API가 오류에 토큰 수를 보고하지 않는 경우 메시지는 다음과 같습니다.2457교환이 하나뿐인 대화에는 요약할 이전 턴이 없습니다. 이러한 대화에서 자동 압축이 실행될 상황이 되면 Claude Code는 시도를 건너뛰고, 대신 요청을 채우고 있는 내용이 무엇인지 설명합니다. API가 오류에서 토큰 수를 보고하지 않으면 메시지는 다음과 같습니다:
2442 2458
2443```text theme={null}2459```text theme={null}
2444Prompt is too long · this conversation is a single exchange and cannot be compacted — the request size comes mostly from system prompt, tool definitions, or attachments.2460Prompt is too long · this conversation is a single exchange and cannot be compacted — the request size comes mostly from system prompt, tool definitions, or attachments.
2445```2461```
2446 2462
2447API가 오류에 토큰 수를 보고하는 경우, Claude Code는 이를 대화 크기에 대한 자체 추정치와 비교하여 요청의 대부분이 대화 자체의 내용인지, 아니면 Claude Code가 함께 보내는 시스템 프롬프트, 도구 정의, 첨부 파일 내용인지 판단합니다. 대화 자체의 내용이 요청의 대부분을 차지하는 경우 메시지는 다음과 같습니다.2463API가 오류에서 토큰 수를 보고하면, Claude Code는 이를 대화 크기에 대한 자체 추정치와 비교하여 요청의 대부분을 차지하는 것이 대화 자체의 내용인지, 아니면 Claude Code가 함께 보내는 시스템 프롬프트, 도구 정의, 첨부 내용인지 판단합니다. 대화 자체의 내용이 요청의 대부분을 차지하면 메시지는 다음과 같습니다:
2448 2464
2449```text theme={null}2465```text theme={null}
2450Prompt is too long · the request is ~<request tokens> tokens (limit <limit>) and this conversation's own content is most of it. A single-exchange conversation cannot be compacted; start with less content (smaller files or pasted text).2466Prompt is too long · the request is ~<request tokens> tokens (limit <limit>) and this conversation's own content is most of it. A single-exchange conversation cannot be compacted; start with less content (smaller files or pasted text).
2451```2467```
2452 2468
2453요청의 대부분이 대화 외부에 있는 경우 메시지는 다음과 같습니다.2469요청의 대부분이 대화 외부에 있으면 메시지는 다음과 같습니다:
2454 2470
2455```text theme={null}2471```text theme={null}
2456Prompt is too long · the request is ~<request tokens> tokens (limit <limit>) but this conversation is only ~<conversation tokens> tokens — the rest is system prompt, tool definitions, and attachment content. A single-exchange conversation cannot be compacted; reduce attached files/tools or start with less context.2472Prompt is too long · the request is ~<request tokens> tokens (limit <limit>) but this conversation is only ~<conversation tokens> tokens — the rest is system prompt, tool definitions, and attachment content. A single-exchange conversation cannot be compacted; reduce attached files/tools or start with less context.
2457```2473```
2458 2474
2459v2.1.162 이전에는 Claude Code가 그래도 압축을 시도했고, 실패하면 `Prompt is too long`만 표시했습니다.2475v2.1.162 이전에는 Claude Code가 그럼에도 압축을 시도했고, 실패하면 `Prompt is too long`만 표시했습니다.
2460 2476
2461**해결 방법:**2477**해결 방법:**
2462 2478
2463* `/compact`를 실행하여 이전 턴을 요약하고 공간을 확보하거나, `/clear`를 실행하여 새로 시작하십시오. `/compact`가 `Not enough messages to compact.`로 응답하면 대화가 요약할 이전 내용이 없는 단일 교환이라는 뜻이므로, 공간은 그 하나의 프롬프트와 Claude Code가 모든 요청에 함께 보내는 내용이 차지하고 있습니다. `/clear`를 실행한 후 붙여넣는 텍스트를 줄이거나 더 작은 첨부 파일로 다시 보내거나, 아래 단계에 따라 도구 정의와 메모리 파일을 줄이십시오2479* `/compact`를 실행하여 이전 턴을 요약하고 공간을 확보하거나, `/clear`를 실행하여 새로 시작하세요. `/compact`가 `Not enough messages to compact.`로 응답하면 대화가 요약할 이전 내용이 없는 단일 교환이라는 뜻이므로, 공간은 해당 프롬프트 하나와 Claude Code가 모든 요청과 함께 보내는 내용이 차지하고 있습니다. `/clear`를 실행하고 붙여넣는 텍스트를 줄이거나 더 작은 첨부 파일로 다시 보내거나, 아래 단계에 따라 도구 정의와 메모리 파일을 줄이세요
2464* `/context`를 실행하면 시스템 프롬프트, 도구, 메모리 파일, 메시지 등 무엇이 윈도우를 차지하고 있는지 세부 내역을 확인할 수 있습니다2480* `/context`를 실행하여 윈도우를 차지하는 항목(시스템 프롬프트, 도구, 메모리 파일, 메시지)의 내역을 확인하세요
2465* 사용하지 않는 MCP 서버를 `/mcp disable <name>`으로 비활성화하여 해당 도구 정의를 컨텍스트에서 제거하십시오2481* 사용하지 않는 MCP 서버를 `/mcp disable <name>`으로 비활성화하여 해당 도구 정의를 컨텍스트에서 제거하세요
2466* 큰 `CLAUDE.md` 메모리 파일을 줄이거나, 관련이 있을 때만 로드되는 [경로 범위 규칙](https://code.claude.com/docs/ko/memory.md#path-specific-rules)으로 지침을 옮기십시오2482* 큰 `CLAUDE.md` 메모리 파일을 줄이거나, 관련 있을 때만 로드되는 [경로 범위 규칙](https://code.claude.com/docs/ko/memory.md#path-specific-rules)으로 지침을 옮기세요
2467* 자동 압축은 기본적으로 켜져 있으며 일반적으로 이 오류를 방지합니다. `/config`에서 또는 [`DISABLE_AUTO_COMPACT`](https://code.claude.com/docs/ko/env-vars)로 자동 압축을 끈 경우 다시 켜십시오. 계속 끈 상태로 두려면 윈도우가 가득 차기 전에 직접 `/compact`를 실행하십시오.2483* 자동 압축은 기본적으로 켜져 있으며 일반적으로 이 오류를 방지합니다. `/config` 또는 [`DISABLE_AUTO_COMPACT`](https://code.claude.com/docs/ko/env-vars)로 자동 압축을 끈 경우 다시 켜세요. 계속 꺼 두려면 윈도우가 가득 차기 전에 직접 `/compact`를 실행하세요.
2468* 더 큰 컨텍스트를 지원하는 모델에서 200K 토큰 근처에서 오류가 발생한다면, Claude Code가 인식하지 못하는 모델 ID가 원인일 수 있습니다. Claude Code는 이런 ID에 대해 200K 윈도우를 가정하므로, 그 이상으로 계속 작업하려면 [모델의 실제 컨텍스트 윈도우를 지정](https://code.claude.com/docs/ko/model-config.md#correct-the-window-for-a-gateway-or-custom-model-id)하십시오.2484* 더 많은 토큰을 허용하는 모델에서 200K 토큰 근처에서 오류가 나타난다면, Claude Code가 인식하지 못하는 모델 ID가 한 가지 원인입니다. Claude Code는 이러한 ID에 대해 200K 윈도우를 가정하므로, 그 이상으로 계속 작업하려면 [모델의 실제 컨텍스트 윈도우를 지정하세요](https://code.claude.com/docs/ko/model-config.md#correct-the-window-for-a-gateway-or-custom-model-id).
2469 * 사용자 지정 [`ANTHROPIC_BASE_URL`](https://code.claude.com/docs/ko/env-vars)을 사용하고 오류가 `Prompt is too long · automatic compaction failed`로 시작한다면, [모델의 컨텍스트 윈도우를 설정](https://code.claude.com/docs/ko/model-config.md#correct-the-window-for-a-gateway-or-custom-model-id)하거나 v2.1.299 이상으로 [업데이트](https://code.claude.com/docs/ko/setup.md#update-claude-code)하십시오. v2.1.299 이전에는 Claude Code가 가정된 200K 윈도우 근처에서 요청을 보내는 대신 해당 메시지와 함께 턴을 종료했습니다.2485 * 사용자 지정 [`ANTHROPIC_BASE_URL`](https://code.claude.com/docs/ko/env-vars)을 사용하고 오류가 `Prompt is too long · automatic compaction failed`로 시작하면, [모델의 컨텍스트 윈도우를 설정](https://code.claude.com/docs/ko/model-config.md#correct-the-window-for-a-gateway-or-custom-model-id)하거나 v2.1.299 이상으로 [업데이트](https://code.claude.com/docs/ko/setup.md#update-claude-code)하세요. v2.1.299 이전에는 Claude Code가 가정된 200K 윈도우 근처에서 요청을 보내는 대신 해당 메시지와 함께 턴을 종료했습니다.
2470* Claude가 대화를 압축하는 도중에 중지한 직후 오류가 나타났다면, 대화는 변경되지 않았으며 여전히 압축이 필요할 만큼 큽니다. `/compact`를 실행하고 메시지를 다시 보내십시오. 오류가 재발하지 않도록 하려면 [Claude Code를 업데이트](https://code.claude.com/docs/ko/setup.md#update-claude-code)하여 v2.1.304 이상으로 만드십시오. v2.1.304 이전에는 그 시점에 중지하면 이 오류와 함께 턴이 종료될 수 있었습니다.2486* Claude가 대화를 압축하는 동안 중지한 직후에 오류가 나타났다면, 대화는 변경되지 않았으며 여전히 압축이 필요할 만큼 큽니다. `/compact`를 실행하고 메시지를 다시 보내세요. 오류가 재발하지 않도록 하려면 v2.1.304 이상으로 [Claude Code를 업데이트](https://code.claude.com/docs/ko/setup.md#update-claude-code)하세요. v2.1.304 이전에는 이 시점에 중지하면 이 오류와 함께 턴이 종료될 수 있었습니다.
2471* v2.1.305에서 MCP 도구가 많고 Anthropic API에 직접 연결된 경우, 이 오류가 API의 관련 없는 400 또는 422 오류를 가릴 수 있습니다. 원래 오류를 확인하려면 [Claude Code를 업데이트](https://code.claude.com/docs/ko/setup.md#update-claude-code)하여 v2.1.306 이상으로 만드십시오.2487* v2.1.305에서 MCP 도구가 많고 Anthropic API에 직접 연결된 경우, 이 오류가 API의 관련 없는 400 또는 422 오류를 가릴 수 있습니다. 원래 오류를 확인하려면 v2.1.306 이상으로 [Claude Code를 업데이트](https://code.claude.com/docs/ko/setup.md#update-claude-code)하세요.
2472 2488
2473컨텍스트가 채워지는 방식을 대화형으로 보려면 [컨텍스트 윈도우 살펴보기](https://code.claude.com/docs/ko/context-window.md)를 참조하십시오.2489컨텍스트가 채워지는 방식을 대화형으로 살펴보려면 [컨텍스트 윈도우 살펴보기](https://code.claude.com/docs/ko/context-window.md)를 참조하세요.
2474 2490
2475### 컨텍스트가 토큰 한도를 초과함2491### Context exceeds the token limit
2476 2492
2477대화가 모델의 컨텍스트 윈도우를 넘어설 만큼 커지면 `/context`는 출력 상단에 다음 경고를 표시합니다:2493대화가 모델의 컨텍스트 윈도우를 넘어서면 `/context`는 출력 상단에 다음 경고를 표시합니다:
2478 2494
2479```text theme={null}2495```text theme={null}
2480Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.2496Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.
2481```2497```
2482 2498
2483`Context exceeds` 경고가 표시된 후, 기본값인 [자동 압축](https://code.claude.com/docs/ko/settings-reference.md#autocompactenabled)이 켜져 있는 동안에는 두 명령 중 어느 것도 실행할 필요가 없습니다:2499`Context exceeds` 경고가 표시된 후에도 [자동 압축](https://code.claude.com/docs/ko/settings-reference.md#autocompactenabled)이 켜져 있는 동안(기본값)에는 두 명령 중 어느 것도 실행할 필요가 없습니다:
2484 2500
2485* **자동 압축 켜짐**: 다음 메시지를 보내세요. 여전히 [`Prompt is too long`](#prompt-is-too-long)으로 실패하면 해당 항목을 참조하세요.2501* **자동 압축 켜짐**: 다음 메시지를 보내세요. 여전히 [`Prompt is too long`](#prompt-is-too-long)으로 실패하면 해당 항목을 참조하세요.
2486* **자동 압축 꺼짐**: 세션에서 경고에 `/compact`가 표시되어 있으면 이를 실행하고, 그렇지 않으면 `/clear`를 실행하여 다시 시작하세요. 둘 중 하나를 실행하기 전까지 메시지는 `Context limit reached`로 실패하며, `-p` 출력에서는 `Prompt is too long`으로 실패합니다.2502* **자동 압축 꺼짐**: 세션에서 경고에 `/compact`가 표시되어 있으면 이를 실행하거나, `/clear`를 실행하여 다시 시작하세요. 둘 중 하나를 실행하기 전까지는 메시지가 `Context limit reached`(`-p` 출력에서는 `Prompt is too long`)로 실패합니다.
2487 2503
2488초과한 한도가 1M 컨텍스트 모델의 200K 경계처럼 압축 윈도우인 경우 경고 문구가 다릅니다. 압축 윈도우는 모델의 컨텍스트 윈도우보다 작을 수 있으므로, 이를 넘어선 요청도 여전히 성공할 수 있습니다.2504초과한 한도가 1M 컨텍스트 모델의 200K 경계와 같은 압축 윈도우인 경우 경고 문구가 다릅니다. 압축 윈도우는 모델의 컨텍스트 윈도우보다 작을 수 있으므로, 이를 넘어선 요청도 여전히 성공할 수 있습니다.
2489 2505
2490```text theme={null}2506```text theme={null}
2491Context is 94k tokens past the 200k-token compaction window — run /compact to reduce usage.2507Context is 94k tokens past the 200k-token compaction window — run /compact to reduce usage.
2496**해결 방법:**2512**해결 방법:**
2497 2513
2498* **압축 윈도우 경고 후**: 여러 턴으로 이루어진 대화에서는 `/compact`를 실행하여 이전 턴을 요약하고 공간을 확보하세요. 대신 새로 시작하려면 `/clear`를 실행하세요.2514* **압축 윈도우 경고 후**: 여러 턴으로 이루어진 대화에서는 `/compact`를 실행하여 이전 턴을 요약하고 공간을 확보하세요. 대신 새로 시작하려면 `/clear`를 실행하세요.
2499* 사용량을 줄이는 더 많은 방법은 [Prompt is too long](#prompt-is-too-long)을 참조하십시오2515* 사용량을 줄이는 다른 방법은 [Prompt is too long](#prompt-is-too-long)을 참조하세요
2500 2516
2501v2.1.216 이전에는 `/context`가 100%를 넘는 사용량을 표시하면서도 그 의미나 복구 방법을 설명하는 경고 줄을 표시하지 않았습니다.2517v2.1.216 이전에는 `/context`가 100%를 넘는 사용량을 표시하면서도 그 의미나 복구 방법을 설명하는 경고 줄을 표시하지 않았습니다.
2502 2518
2503### Request too large2519### Request too large
2504 2520
2505토큰화 이전의 원시 요청 본문이 API의 32MB 한도를 초과했습니다. 보통 큰 붙여넣기 내용, 도구 결과 또는 첨부 파일 때문입니다. 이 한도는 [컨텍스트 윈도우](#prompt-is-too-long)와는 별개입니다.2521원시 요청 본문이 토큰화 전에 API의 32MB 한도를 초과했습니다. 대개 크게 붙여넣은 내용, 도구 결과 또는 첨부 파일 때문입니다. 이 한도는 [컨텍스트 윈도우](#prompt-is-too-long)와는 별개입니다.
2506 2522
2507```text theme={null}2523```text theme={null}
2508Request too large (max 32MB). Accumulated images and attachments in the conversation pushed the request over the limit. Run /compact, or double press esc to go back and remove attachments.2524Request too large (max 32MB). Accumulated images and attachments in the conversation pushed the request over the limit. Run /compact, or double press esc to go back and remove attachments.
2509```2525```
2510 2526
2511요청이 Claude API로 직접 전송되었고 API 자체가 이를 거부한 경우, Claude Code는 대화 크기를 측정하고 복구가 가능한지에 따라 메시지 문구를 정합니다. 프록시, 게이트웨이 또는 클라우드 제공업체를 거친 경우에는 일반 메시지가 표시됩니다. 측정된 형식은 다음과 같습니다.2527요청이 Claude API로 직접 전송되었고 API 자체가 이를 거부한 경우, Claude Code는 대화를 측정하고 복구가 가능한지에 따라 메시지 문구를 결정합니다. 프록시, 게이트웨이 또는 클라우드 제공업체를 거친 경우에는 일반 메시지가 표시됩니다. 측정된 형식은 다음과 같습니다:
2512 2528
2513* `Request too large (max 32MB; 20.1MB of about 33.4MB is images or documents).`: 이미지나 문서 때문에 요청이 한도를 초과했습니다. Claude Code는 이를 제거한 후 재시도합니다.2529* `Request too large (max 32MB; 20.1MB of about 33.4MB is images or documents).`: 이미지나 문서 때문에 요청이 한도를 초과했습니다. Claude Code는 이를 제거하고 재시도합니다.
2514* `Request too large for the API's 32MB request limit`: 메시지만으로도 한도를 초과하므로 메시지에 `compacting cannot make it fit`이 표시되며 Claude Code는 재시도하지 않습니다. [비대화형 모드](https://code.claude.com/docs/ko/headless.md)에서는 대신 입력을 줄이거나 새 세션을 시작하라는 메시지가 표시됩니다.2530* `Request too large for the API's 32MB request limit`: 메시지만으로도 한도를 초과하므로, 메시지에 `compacting cannot make it fit`이 표시되고 Claude Code는 재시도하지 않습니다. [비대화형 모드](https://code.claude.com/docs/ko/headless.md)에서는 메시지가 대신 입력을 줄이거나 새 세션을 시작하라고 안내합니다.
2515 2531
2516v2.1.212 이전에는 이미지가 충분히 누적된 대화가 매 턴마다 `Request too large (max 32MB). Double press esc to go back and try with a smaller file.`로 실패했습니다. v2.1.229 이전에는 압축으로 해결할 수 없는 경우에도 Claude Code가 모든 거부에 대해 첨부 파일 관련 조언을 표시했습니다.2532v2.1.212 이전에는 이미지가 충분히 누적된 대화가 매 턴마다 `Request too large (max 32MB). Double press esc to go back and try with a smaller file.`로 실패했습니다. v2.1.229 이전에는 압축이 도움이 되지 않는 경우에도 Claude Code가 모든 거부에 대해 첨부 파일 관련 조언을 표시했습니다.
2517 2533
2518**해결 방법:**2534**해결 방법:**
2519 2535
2520* 메시지에 `compacting cannot make it fit`이 표시되면 Esc를 두 번 눌러 큰 내용을 추가한 턴 이전으로 되돌아가거나, `/clear`를 실행하여 새로 시작하십시오2536* 메시지에 `compacting cannot make it fit`이 표시되면 Esc를 두 번 눌러 큰 내용을 추가한 턴 이전으로 돌아가거나, `/clear`를 실행하여 새로 시작하세요
2521* 그렇지 않으면 누적된 이미지와 첨부 파일을 제거하는 `/compact`를 실행하십시오2537* 그렇지 않으면 누적된 이미지와 첨부 파일을 제거하는 `/compact`를 실행하세요
2522* 큰 파일은 내용을 붙여넣는 대신 경로로 참조하여 Claude가 나누어 읽을 수 있도록 하십시오2538* 큰 파일은 내용을 붙여넣는 대신 경로로 참조하여 Claude가 나누어 읽을 수 있도록 하세요
2523* 이미지의 경우 아래의 [Image was too large](#image-was-too-large)를 참조하십시오2539* 이미지의 경우 아래 [Image was too large](#image-was-too-large)를 참조하세요
2524 2540
2525### Image was too large2541### Image was too large
2526 2542
2527붙여넣거나 첨부한 이미지가 API의 크기 또는 해상도 한도를 초과했습니다.2543붙여넣거나 첨부한 이미지가 API의 크기 또는 치수 한도를 초과합니다.
2528 2544
2529```text theme={null}2545```text theme={null}
2530Image was too large. Double press esc to go back and try again with a smaller image.2546Image was too large. Double press esc to go back and try again with a smaller image.
2533An image in the conversation exceeds the dimension limit for many-image requests (3000px). Run /compact to remove old images from context, or start a new session.2549An image in the conversation exceeds the dimension limit for many-image requests (3000px). Run /compact to remove old images from context, or start a new session.
2534```2550```
2535 2551
2536`could not be processed and was removed` 줄은 크기 또는 해상도 한도를 초과하는 이미지 등 대화 내의 이미지를 API가 거부했다는 의미입니다.2552`could not be processed and was removed` 줄은 API가 대화의 이미지(예: 크기 또는 치수 한도를 초과한 이미지)를 거부했음을 의미합니다.
2537 2553
2538이러한 오류 중 하나가 계속 반복된다면 Claude Code를 업데이트하십시오. 이전 버전에서는 다음과 같은 이유로 이미지 오류가 반복될 수 있었습니다.2554이러한 오류 중 하나가 계속 반복되면 Claude Code를 업데이트하세요. 이전 버전에서는 다음과 같은 이유로 이미지 오류가 반복될 수 있었습니다:
2539 2555
2540* v2.1.299 이전에는 이미지가 많은 긴 대화에서 Claude Code가 한도를 초과한 이미지 대신 마지막으로 첨부한 이미지를 제거할 수 있었습니다. 그러면 `was removed` 줄이 매 턴마다 반복되었고 Claude는 새 이미지를 보지 못했습니다.2556* v2.1.299 이전에는 이미지가 많은 긴 대화에서 Claude Code가 한도를 초과한 이미지 대신 마지막으로 첨부한 이미지를 제거할 수 있었습니다. 그러면 `was removed` 줄이 매 턴마다 반복되었고, Claude는 새 이미지를 보지 못했습니다.
2541* v2.1.299 이전에는 VS Code, Desktop 앱, Agent SDK에서 Claude가 작업하는 동안 첨부한 이미지가 다른 첨부 이미지와 달리 크기 조정되지 않았습니다. 이 이미지들은 원래 크기 그대로 API에 전달되어 긴 대화에서 이미지 오류가 반복되었습니다.2557* v2.1.299 이전에는 VS Code, Desktop 앱, Agent SDK에서 Claude가 작업하는 동안 첨부한 이미지가 다른 첨부 이미지처럼 크기 조정되지 않았습니다. 이러한 이미지는 원래 크기로 API에 전달되어 긴 대화에서 이미지 오류가 반복되는 원인이 되었습니다.
2542* v2.1.166 이전에는 붙여넣은 이미지가 대화에 남아 이후 모든 메시지에서 같은 오류가 반복될 수 있었습니다2558* v2.1.166 이전에는 붙여넣은 이미지가 대화에 남아 이후 모든 메시지에서 같은 오류가 반복될 수 있었습니다
2543 2559
2544**해결 방법:**2560**해결 방법:**
2545 2561
2546* 붙여넣기 전에 이미지 크기를 조정하십시오. API는 단일 이미지의 경우 가장 긴 변 기준 8000픽셀까지, 컨텍스트에 이미지가 20개를 초과하는 경우 3000픽셀까지 허용합니다.2562* 붙여넣기 전에 이미지 크기를 조정하세요. API는 단일 이미지의 경우 가장 긴 변이 최대 8000픽셀, 컨텍스트에 이미지가 20개를 넘는 경우 최대 3000픽셀인 이미지를 허용합니다.
2547* 전체 화면 대신 관련 영역만 더 좁게 스크린샷을 찍으십시오2563* 전체 화면 대신 관련 영역만 좁게 스크린샷을 찍으세요
2548* `dimension limit for many-image requests` 메시지의 경우, 메시지에 `/compact`가 언급되어 있으면 Claude Code 프롬프트에서 이를 실행하거나, 이미지가 더 적은 새 세션을 시작하십시오2564* `dimension limit for many-image requests` 메시지의 경우, 메시지에 `/compact`가 표시되어 있으면 Claude Code 프롬프트에서 이를 실행하거나, 이미지를 줄여 새 세션을 시작하세요
2549 2565
2550`dimension limit for many-image requests` 메시지에는 API 오류에 명시된 픽셀 한도가 표시됩니다.2566`dimension limit for many-image requests` 메시지에는 API 오류에 명시된 픽셀 한도가 표시됩니다.
2551 2567
2563Unable to resize image — its pixels could not be decoded (the file may be damaged, or use an encoding Claude Code cannot read), and it is over the … API limit (… raw, … base64), so it cannot be sent. Re-save it as a PNG or JPEG and try again.2579Unable to resize image — its pixels could not be decoded (the file may be damaged, or use an encoding Claude Code cannot read), and it is over the … API limit (… raw, … base64), so it cannot be sent. Re-save it as a PNG or JPEG and try again.
2564```2580```
2565 2581
2566Claude Code는 일반적으로 큰 이미지를 자동으로 크기 조정합니다. 이 오류들은 이미지를 디코딩할 수 없었거나 API 한도에 맞게 크기를 조정할 수 없었다는 의미입니다.2582Claude Code는 일반적으로 큰 이미지의 크기를 자동으로 조정합니다. 이러한 오류는 이미지를 디코딩할 수 없었거나 API 한도에 맞게 크기를 조정할 수 없었음을 의미합니다.
2583
2584표시되는 오류에는 이 예시의 `2000x2000px` 대신 `2576x2576px`와 같은 다른 픽셀 한도가 명시될 수 있습니다.
2567 2585
2568**해결 방법:**2586**해결 방법:**
2569 2587
2570* 메시지에서 이미지 변환을 요청하면 PNG, JPEG, GIF 또는 WebP로 변환한 후 다시 첨부하십시오. Claude Code는 이러한 형식에 대해 이미지를 디코딩하지 않고도 파일 헤더에서 해상도를 확인할 수 있습니다.2588* 메시지에서 이미지 변환을 요청하면 PNG, JPEG, GIF 또는 WebP로 변환한 후 다시 첨부하세요. Claude Code는 이러한 형식의 경우 이미지를 디코딩하지 않고도 파일 헤더에서 치수를 확인할 수 있습니다.
2571* 메시지에 해상도 또는 크기 한도가 표시되면, 첨부하기 전에 해당 한도 이하로 이미지 크기를 조정하거나 다시 압축하십시오.2589* 메시지에 치수 또는 크기 한도가 표시되면 첨부하기 전에 이미지를 해당 한도 미만으로 크기 조정하거나 다시 압축하세요.
2572* 메시지에 CMYK JPEG, 애니메이션 WebP, 손상되었을 수 있는 파일 등의 원인이 표시되면, 메시지가 제안하는 형식으로 이미지를 다시 저장한 후 다시 첨부하십시오.2590* 메시지에 CMYK JPEG, 애니메이션 WebP, 손상되었을 수 있는 파일과 같은 원인이 명시되어 있으면 메시지가 제안하는 형식으로 이미지를 다시 저장한 후 다시 첨부하세요.
2573 2591
2574### Request rejected as unprocessable by the model2592### Request rejected as unprocessable by the model
2575 2593
2576API가 모델이 처리할 수 없는 요청이라며 요청을 거부했습니다. 이 메시지는 API 자체의 메시지입니다.2594API가 모델이 처리할 수 없는 요청으로 판단하여 요청을 거부했습니다. 이 메시지는 API 자체의 메시지입니다.
2577 2595
2578```text theme={null}2596```text theme={null}
2579API Error: 400 Request rejected as unprocessable by the model (too many or oversized images, or unsupported parameters)2597API Error: 400 Request rejected as unprocessable by the model (too many or oversized images, or unsupported parameters)
2580```2598```
2581 2599
2582Claude Code는 거부된 요청에서 가장 오래된 이미지와 문서를 제거한 후 다시 보낼 수 있습니다. v2.1.290 이전에는 Claude Code가 이 거부에 대해 이미지를 제거하지 않았기 때문에, 수백 개의 이미지가 누적된 긴 세션은 매 턴마다 이 오류로 실패할 수 있었습니다.2600Claude Code는 거부된 요청에서 가장 오래된 이미지와 문서를 제거하고 다시 보낼 수 있습니다. v2.1.290 이전에는 Claude Code가 이 거부에 대해 이미지를 제거하지 않았기 때문에, 수백 개의 이미지가 누적된 긴 세션은 매 턴마다 이 오류로 실패할 수 있었습니다.
2583 2601
2584**해결 방법:**2602**해결 방법:**
2585 2603
2586* 이미지나 문서가 포함된 대화에서 메시지가 계속 나타나면 직접 제거하십시오. Esc를 두 번 눌러 이를 추가한 턴 이전으로 되돌아가거나, `/clear`를 실행하여 새로 시작하십시오.2604* 이미지나 문서가 있는 대화에서 메시지가 계속 나타나면 직접 제거하세요. Esc를 두 번 눌러 해당 항목을 추가한 턴 이전으로 돌아가거나, `/clear`를 실행하여 새로 시작하세요.
2587 2605
2588### PDF 오류2606### PDF 오류
2589 2607
2590첨부한 PDF를 처리할 수 없습니다. 여기에는 메시지가 비대화형 형식으로 표시되어 있으며, 대화형 세션에서는 대신 esc를 두 번 눌러 다시 시도하라고 안내합니다.2608첨부한 PDF를 처리할 수 없었습니다. 여기에 표시된 메시지는 비대화형 형식이며, 대화형 세션에서는 대신 esc를 두 번 눌러 다시 시도하라는 안내가 표시됩니다.
2591 2609
2592```text theme={null}2610```text theme={null}
2593PDF too large (max 100 pages, 20MB). Try reading the file a different way (e.g., extract text with pdftotext).2611PDF too large (max 100 pages, 20MB). Try reading the file a different way (e.g., extract text with pdftotext).
2597 2615
2598**해결 방법:**2616**해결 방법:**
2599 2617
2600* 너무 큰 PDF의 경우, 전체 파일을 첨부하는 대신 Claude에게 Read 도구로 페이지 범위를 읽도록 요청하거나, `pdftotext` 같은 도구로 텍스트를 추출한 후 출력 파일을 경로로 참조하십시오2618* 크기가 큰 PDF의 경우 전체 파일을 첨부하는 대신 Claude에게 Read 도구로 페이지 범위를 읽도록 요청하거나, `pdftotext` 같은 도구로 텍스트를 추출한 후 출력 파일을 경로로 참조하세요
2601* 보호되었거나 유효하지 않은 PDF의 경우, 비밀번호를 제거하거나 원본 애플리케이션에서 파일을 다시 내보낸 후 다시 시도하십시오2619* 보호되었거나 유효하지 않은 PDF의 경우 암호를 제거하거나 원본 애플리케이션에서 파일을 다시 내보낸 후 다시 시도하세요
2602 2620
2603Claude가 Read 도구로 PDF의 페이지 범위를 읽을 때, 다른 메시지와 함께 읽기가 실패할 수 있습니다.2621Claude가 Read 도구로 PDF의 페이지 범위를 읽을 때 다음과 같은 다른 메시지와 함께 읽기가 실패할 수 있습니다:
2604 2622
2605```text theme={null}2623```text theme={null}
2606pdftoppm is not installed. Install poppler-utils (e.g. `brew install poppler` or `apt-get install poppler-utils`) to enable PDF page rendering.2624pdftoppm is not installed. Install poppler-utils (e.g. `brew install poppler` or `apt-get install poppler-utils`) to enable PDF page rendering.
2607```2625```
2608 2626
2609페이지 범위 읽기는 `pdftoppm`으로 페이지를 렌더링합니다. 메시지에 제시된 명령으로 poppler-utils를 설치하거나, 다른 플랫폼에서는 `pdftoppm`을 `PATH`에 추가하는 poppler 빌드를 설치하십시오. 어떤 PDF가 페이지 범위로 읽히는지는 [Read 도구 동작](https://code.claude.com/docs/ko/tools-reference.md#read-tool-behavior)을 참조하십시오.2627페이지 범위 읽기는 `pdftoppm`으로 페이지를 렌더링합니다. 메시지에 제시된 명령으로 poppler-utils를 설치하거나, 다른 플랫폼에서는 `pdftoppm`을 `PATH`에 추가하는 poppler 빌드를 설치하세요. 어떤 PDF가 페이지 범위로 읽히는지는 [Read 도구 동작](https://code.claude.com/docs/ko/tools-reference.md#read-tool-behavior)을 참조하세요.
2610 2628
2611### Extra inputs are not permitted2629### Extra inputs are not permitted
2612 2630
2613요청을 받은 엔드포인트가 요청의 필드 중 하나를 허용하지 않는 입력으로 거부했으며, 엔드포인트의 메시지에 해당 필드가 표시됩니다.2631요청을 받은 엔드포인트가 요청의 필드 중 하나를 허용하지 않는 입력으로 판단하여 거부했으며, 엔드포인트의 메시지에 해당 필드가 명시됩니다.
2614 2632
2615```text theme={null}2633```text theme={null}
2616API Error: 400 ... context_management: Extra inputs are not permitted2634API Error: 400 ... context_management: Extra inputs are not permitted
2617```2635```
2618 2636
2619Claude Code는 `context_management`나 도구 검색의 `defer_loading` 같은 베타 전용 필드를 이를 활성화하는 `anthropic-beta` 헤더와 함께 보냅니다. 게이트웨이가 본문은 전달하지만 헤더를 누락하면 API는 인식하지 못하는 필드를 보게 됩니다. 게이트웨이가 Anthropic 형식의 본문을 스키마가 다른 업스트림으로 전달하면, 해당 업스트림이 이러한 필드를 거부합니다. [베타 헤더와 본문 필드 쌍](https://code.claude.com/docs/ko/llm-gateway-protocol.md#beta-header-and-body-field-pairs)에서 두 경우를 모두 다룹니다.2637Claude Code는 `context_management` 및 도구 검색의 `defer_loading`과 같은 베타 전용 필드를, 이를 활성화하는 `anthropic-beta` 헤더와 함께 보냅니다. 게이트웨이가 본문은 전달하지만 헤더를 제거하면 API는 인식할 수 없는 필드를 받게 됩니다. 게이트웨이가 Anthropic 형식의 본문을 다른 스키마를 사용하는 업스트림으로 전달하면 해당 업스트림이 이러한 필드를 거부합니다. [베타 헤더와 본문 필드 쌍](https://code.claude.com/docs/ko/llm-gateway-protocol.md#beta-header-and-body-field-pairs)에서 두 경우를 모두 다룹니다.
2620 2638
2621**해결 방법:**2639**해결 방법:**
2622 2640
2623* 메시지에 `context_management: Extra inputs are not permitted`가 포함되어 있으면 [Claude Code를 업데이트](https://code.claude.com/docs/ko/setup.md#update-claude-code)하여 v2.1.304 이상으로 만드십시오. 업데이트 후에는 Claude Code가 이 거부에 대해 해당 필드 없이 요청을 한 번 더 보냅니다. v2.1.304 이전에는 Claude Code가 이 거부를 재시도하지 않았습니다.2641* 메시지에 `context_management: Extra inputs are not permitted`가 포함되어 있으면 v2.1.304 이상으로 [Claude Code를 업데이트](https://code.claude.com/docs/ko/setup.md#update-claude-code)하세요. 업데이트 후에는 Claude Code가 이 거부에 대응하여 해당 필드 없이 요청을 한 번 더 보냅니다. v2.1.304 이전에는 Claude Code가 이 거부에 대해 재시도하지 않았습니다.
2624* 메시지에 `defer_loading` 또는 `tool_reference`가 표시되면 [Claude Code를 업데이트](https://code.claude.com/docs/ko/setup.md#update-claude-code)하여 v2.1.305 이상으로 만드십시오. 그러면 Claude Code는 이 거부에 대해 도구 검색 필드 없이 [요청을 한 번 더 보냅니다](https://code.claude.com/docs/ko/llm-gateway-protocol.md#retry-without-tool-search).2642* 메시지에 `defer_loading` 또는 `tool_reference`가 명시되어 있으면 v2.1.305 이상으로 [Claude Code를 업데이트](https://code.claude.com/docs/ko/setup.md#update-claude-code)하세요. 그러면 Claude Code는 이 거부에 대응하여 도구 검색 필드 없이 [요청을 한 번 더 보냅니다](https://code.claude.com/docs/ko/llm-gateway-protocol.md#retry-without-tool-search).
2625* 게이트웨이가 헤더를 누락한다면 `anthropic-beta` 헤더를 전달하도록 구성하십시오. 게이트웨이가 전달해야 하는 항목은 [기능 패스스루](https://code.claude.com/docs/ko/llm-gateway-protocol.md#feature-pass-through)를 참조하십시오.2643* 게이트웨이가 헤더를 제거하는 경우 `anthropic-beta` 헤더를 전달하도록 구성하세요. 게이트웨이가 전달해야 하는 항목은 [기능 패스스루](https://code.claude.com/docs/ko/llm-gateway-protocol.md#feature-pass-through)를 참조하세요.
2626* 대안으로, 실행하기 전에 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](https://code.claude.com/docs/ko/env-vars)을 설정하십시오. 정확한 적용 범위는 [사전 출시 기능 비활성화](https://code.claude.com/docs/ko/llm-gateway-protocol.md#disable-pre-release-capabilities)에서 다룹니다.2644* 대체 방법으로, 실행하기 전에 [`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1`](https://code.claude.com/docs/ko/env-vars)을 설정하세요. 정확한 적용 범위는 [출시 전 기능 비활성화](https://code.claude.com/docs/ko/llm-gateway-protocol.md#disable-pre-release-capabilities)에서 다룹니다.
2627 2645
2628v2.1.302 이전에는 게이트웨이가 관여하지 않아도 이 오류에 `diagnostics` 필드가 표시될 수 있었습니다. 이는 이미 Anthropic API를 사용한 세션이 재시작 없이 Amazon Bedrock 또는 Google Cloud의 Agent Platform으로 전환될 때 나타났습니다. 예를 들어, 다른 Claude Code 창에서 [`/setup-bedrock`](https://code.claude.com/docs/ko/commands)을 실행하면 열어 둔 세션이 Bedrock으로 전환됩니다. 해당 버전에서는 그 세션에서 `/clear`를 실행하거나 세션을 재시작하십시오.2646v2.1.302 이전에는 게이트웨이가 관여하지 않아도 이 오류에 `diagnostics` 필드가 명시될 수 있었습니다. 이 오류는 이미 Anthropic API를 사용한 세션이 재시작 없이 Amazon Bedrock 또는 Google Cloud의 Agent Platform으로 전환될 때 나타났습니다. 예를 들어 열어 둔 세션은 다른 Claude Code 창에서 [`/setup-bedrock`](https://code.claude.com/docs/ko/commands)을 실행하면 Bedrock으로 전환됩니다. 해당 버전에서는 그 세션에서 `/clear`를 실행하거나 세션을 재시작하세요.
2629 2647
2630### Tool input schema is invalid2648### 도구 입력 스키마가 유효하지 않음
2631 2649
2632요청에 포함된 도구가 API의 JSON Schema 검증에 실패하는 `input_schema`를 선언했기 때문에 API가 요청 전체를 거부했습니다. `tools.` 뒤의 숫자는 요청의 도구 목록에서 실패한 도구의 위치이며, 조회할 수 있는 이름이 아닙니다.2650요청의 도구가 API의 JSON Schema 검증을 통과하지 못하는 `input_schema`를 선언하여 API가 요청 전체를 거부했습니다. `tools.` 뒤의 숫자는 요청의 도구 목록에서 실패한 도구의 위치이며, 조회할 수 있는 이름이 아닙니다.
2633 2651
2634```text theme={null}2652```text theme={null}
2635API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid2653API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid
2638 2656
2639첫 번째 형식은 스키마가 유효한 JSON Schema draft 2020-12가 아니라는 의미입니다. 두 번째 형식은 최상위 속성 이름이 메시지에 인용된 패턴과 일치하지 않는다는 의미입니다.2657첫 번째 형식은 스키마가 유효한 JSON Schema draft 2020-12가 아니라는 의미입니다. 두 번째 형식은 최상위 속성 이름이 메시지에 인용된 패턴과 일치하지 않는다는 의미입니다.
2640 2658
2641Claude Code는 서버의 도구를 로드할 때 [입력 스키마가 이 검증에 실패할 MCP 도구를 제외](https://code.claude.com/docs/ko/mcp.md#tools-with-invalid-input-schemas)하므로, 일반적으로 요청에는 그런 도구가 포함되지 않습니다.2659Claude Code는 서버의 도구를 로드할 때 [이 검증에 실패할 입력 스키마를 가진 MCP 도구를 제외](https://code.claude.com/docs/ko/mcp.md#tools-with-invalid-input-schemas)하므로, 일반적으로 요청에는 그러한 도구가 포함되지 않습니다.
2642 2660
2643[플래그 가져오기가 꺼진 배포](https://code.claude.com/docs/ko/env-vars.md#features-that-need-feature-flag-fetching)나 플래그를 한 번도 받지 못한 머신에서는, Claude Code가 어떤 도구가 거부될지 서버 로그에 기록하지만 그래도 해당 도구를 보내므로 이 오류가 여전히 발생할 수 있습니다.2661[플래그 가져오기가 꺼진 배포](https://code.claude.com/docs/ko/env-vars.md#features-that-need-feature-flag-fetching) 또는 플래그를 한 번도 받지 못한 머신에서는 Claude Code가 어떤 도구가 거부될지를 서버 로그에 기록하지만 해당 도구를 그대로 보내므로, 이 오류가 여전히 발생할 수 있습니다.
2644 2662
2645이 오류는 스키마가 `$schema`에서 draft 2020-12 이외의 JSON Schema 방언을 선언한 도구에 대해서도 발생할 수 있습니다. Claude Code는 이러한 스키마를 JSON Schema 메타 스키마와 대조하여 확인하지 않지만, 최상위 속성 이름 검사는 여전히 적용됩니다.2663이 오류는 `$schema`에서 draft 2020-12 이외의 JSON Schema 방언을 선언하는 스키마를 가진 도구에서도 발생할 수 있습니다. Claude Code는 이러한 스키마를 JSON Schema 메타 스키마와 대조하여 검사하지 않지만, 최상위 속성 이름 검사는 여전히 적용됩니다.
2646 2664
2647v2.1.216 이전에는 어떤 배포에서도 제외 검사가 실행되지 않았습니다.2665v2.1.216 이전에는 어떤 배포에서도 제외 검사가 실행되지 않았습니다.
2648 2666
2649**해결 방법:**2667**해결 방법:**
2650 2668
2651* Claude Code 버전이 v2.1.300 이전이라면 셸에서 [`claude update`](https://code.claude.com/docs/ko/setup#update-claude-code)를 실행하십시오. v2.1.300 이전에는 Claude Code가 [거부된 도구의 매개변수 없이 요청을 재시도](https://code.claude.com/docs/ko/mcp.md#tools-whose-input-schema-the-api-refuses)하지 않았기 때문에, 해당 도구가 포함된 모든 요청에서 이 오류가 반복되었습니다.2669* Claude Code 버전이 v2.1.300 이전이면 셸에서 [`claude update`](https://code.claude.com/docs/ko/setup#update-claude-code)를 실행하세요. v2.1.300 이전에는 Claude Code가 [거부된 도구의 매개변수 없이 요청을 재시도](https://code.claude.com/docs/ko/mcp.md#tools-whose-input-schema-the-api-refuses)하지 않았기 때문에, 해당 도구를 포함한 모든 요청에서 이 오류가 반복되었습니다.
2652* 유효하지 않은 스키마를 선언하는 MCP 서버를 제거하거나 [비활성화](https://code.claude.com/docs/ko/mcp.md#disable-a-server-without-removing-it)하십시오. 오류는 도구를 위치로만 표시합니다. v2.1.216 이상에서는 각 서버의 로그에서 입력 스키마가 거부될 도구를 명시하는 줄을 확인하십시오. 어떤 로그에도 해당 도구가 명시되어 있지 않다면 서버를 하나씩 비활성화하십시오.2670* 유효하지 않은 스키마를 선언하는 MCP 서버를 제거하거나 [비활성화](https://code.claude.com/docs/ko/mcp.md#disable-a-server-without-removing-it)하세요. 오류는 도구를 위치로만 나타냅니다. v2.1.216 이상에서는 각 서버의 로그에서 입력 스키마가 거부될 도구를 명시하는 줄을 확인하세요. 이를 명시하는 로그가 없으면 서버를 하나씩 비활성화하세요.
2653* 서버를 직접 관리한다면 도구의 `input_schema`를 수정하십시오. 스키마는 유효한 JSON Schema여야 하며, 최상위 속성 이름은 1\~64자여야 하고 ASCII 문자와 숫자, `_`, `.`, `-`만 사용해야 합니다. [유효하지 않은 입력 스키마를 가진 도구](https://code.claude.com/docs/ko/mcp.md#tools-with-invalid-input-schemas)를 참조하십시오.2671* 서버를 유지 관리하는 경우 도구의 `input_schema`를 수정하세요. 스키마는 유효한 JSON Schema여야 하며, 최상위 속성 이름은 1\~64자여야 하고 ASCII 문자와 숫자, `_`, `.`, `-`만 사용해야 합니다. [유효하지 않은 입력 스키마를 가진 도구](https://code.claude.com/docs/ko/mcp.md#tools-with-invalid-input-schemas)를 참조하세요.
2654 2672
2655### 128자를 초과하는 MCP 도구 이름2673### 128자를 초과하는 MCP 도구 이름
2656 2674
2657MCP 서버가 나열한 도구의 전체 이름(예: `mcp__<server>__<tool>`)이 API가 허용하는 128자보다 깁니다. Claude Code는 [해당 도구를 Claude에 보내는 도구에서 제외](https://code.claude.com/docs/ko/mcp.md#tools-with-names-longer-than-128-characters)하며, 서버의 다른 도구는 계속 작동합니다. 셸에서 `claude --debug`로 시작한 세션에서는 Claude Code가 `~/.claude/debug/<session-id>.txt`의 디버그 로그에 다음 메시지를 기록합니다.2675MCP 서버가 `mcp__<server>__<tool>`과 같은 전체 이름이 API가 허용하는 128자보다 긴 도구를 나열합니다. Claude Code는 [Claude에게 보내는 도구에서 해당 도구를 제외](https://code.claude.com/docs/ko/mcp.md#tools-with-names-longer-than-128-characters)하며, 서버의 다른 도구는 계속 작동합니다. 셸에서 `claude --debug`로 시작한 세션에서는 Claude Code가 `~/.claude/debug/<session-id>.txt`의 디버그 로그에 다음 메시지를 기록합니다:
2658 2676
2659```text theme={null}2677```text theme={null}
2660Tool "mcp__<server>__<tool>" is not sent to Claude: its name has <N> characters and the API accepts at most 1282678Tool "mcp__<server>__<tool>" is not sent to Claude: its name has <N> characters and the API accepts at most 128
2662 2680
2663**해결 방법:**2681**해결 방법:**
2664 2682
2665* 서버를 직접 관리한다면 도구 이름을 줄이십시오.2683* 서버를 유지 관리하는 경우 도구 이름을 줄이세요.
2666* 서버가 [MCP 구성](https://code.claude.com/docs/ko/mcp.md#mcp-installation-scopes)에 있다면, 그곳에서 `analytics-database` 대신 `db`처럼 더 짧은 이름을 지정하십시오. 그런 다음 [권한 규칙](https://code.claude.com/docs/ko/permissions.md#mcp)과 [훅 matcher](https://code.claude.com/docs/ko/hooks.md#match-mcp-tools)처럼 이전 이름으로 서버나 도구를 참조하는 항목을 업데이트하십시오.2684* 서버가 [MCP 구성](https://code.claude.com/docs/ko/mcp.md#mcp-installation-scopes)에 있는 경우 그곳에서 `analytics-database` 대신 `db`처럼 더 짧은 이름을 지정하세요. 그런 다음 [권한 규칙](https://code.claude.com/docs/ko/permissions.md#mcp)과 [훅 matcher](https://code.claude.com/docs/ko/hooks.md#match-mcp-tools) 등 이전 이름으로 서버나 해당 도구를 참조하는 항목을 업데이트하세요.
2667* [플러그인이 서버를 번들로 제공](https://code.claude.com/docs/ko/mcp.md#plugin-provided-mcp-servers)하는 경우, 도구의 전체 이름에 플러그인 이름도 포함됩니다. 플러그인 관리자에게 서버 또는 도구 이름을 줄여 달라고 요청하십시오.2685* [플러그인이 서버를 번들로 제공](https://code.claude.com/docs/ko/mcp.md#plugin-provided-mcp-servers)하는 경우 도구의 전체 이름에는 플러그인 이름도 포함됩니다. 플러그인 유지 관리자에게 서버 또는 도구 이름을 줄여 달라고 요청하세요.
2668 2686
2669v2.1.292 이전에는 Claude Code가 그래도 해당 도구를 보냈고, API는 이를 포함한 모든 요청을 `API Error: 400 ... tools.N.custom.name: String should have at most 128 characters`로 거부했습니다.2687v2.1.292 이전에는 Claude Code가 해당 도구를 그대로 보냈고, API는 이를 포함한 모든 요청을 `API Error: 400 ... tools.N.custom.name: String should have at most 128 characters`로 거부했습니다.
2670 2688
2671### 200자를 초과하는 tool\_use.name2689### 200자를 초과하는 tool\_use.name
2672 2690
2673대화 기록의 도구 호출에 API가 요청에서 허용하는 200자보다 긴 이름이 포함되어 있습니다.2691대화 기록의 도구 호출에 API가 요청에서 허용하는 200자보다 긴 이름이 포함되어 있습니다:
2674 2692
2675```text theme={null}2693```text theme={null}
2676API Error: 400 ... tool_use.name: String should have at most 200 characters2694API Error: 400 ... tool_use.name: String should have at most 200 characters
2677```2695```
2678 2696
2679Claude Code는 응답이 도착할 때와 저장된 대화를 로드할 때 이런 이름을 200자로 자르므로, 해당 호출은 [`No such tool available`](#no-such-tool-available) 도구 오류로 실패하고 대화는 이 API 오류 없이 계속됩니다.2697Claude Code는 응답이 도착할 때와 저장된 대화를 로드할 때 이러한 이름을 200자로 자르므로, 해당 호출은 [`No such tool available`](#no-such-tool-available) 도구 오류로 실패하고 대화는 이 API 오류 없이 계속됩니다.
2680 2698
2681**해결 방법:**2699**해결 방법:**
2682 2700
2683* `claude update`를 실행한 후 대화를 재개하십시오. 업데이트된 버전은 트랜스크립트를 로드할 때 너무 긴 이름을 복구하므로, 멈춰 있던 대화가 다시 작동합니다.2701* `claude update`를 실행한 후 대화를 재개하세요. 업데이트된 버전은 트랜스크립트를 로드할 때 지나치게 긴 이름을 복구하므로, 막혀 있던 대화가 다시 작동합니다.
2684 2702
2685v2.1.281 이전에는 너무 긴 이름이 기록에 남아 있어 API가 `/compact`와 `--resume`을 포함하여 대화를 다시 보내는 모든 요청을 거부했기 때문에, 이 오류가 반복되고 대화가 멈춰 있었습니다.2703v2.1.281 이전에는 지나치게 긴 이름이 기록에 남아 있었고, API는 `/compact`와 `--resume`을 포함하여 대화를 다시 보내는 모든 요청을 거부했기 때문에 이 오류가 반복되고 대화가 막혔습니다.
2686 2704
2687### There's an issue with the selected model2705### There's an issue with the selected model
2688 2706
2689구성된 모델 이름을 인식할 수 없거나 계정에 해당 모델에 대한 접근 권한이 없습니다. v2.1.160부터 끝부분의 힌트(여기서는 대화형 형식으로 표시됨)는 사용 환경에 따라 다릅니다.2707구성된 모델 이름을 인식할 수 없거나 계정에 해당 모델에 대한 액세스 권한이 없습니다. v2.1.160부터 끝부분의 힌트(여기서는 대화형 형식으로 표시)는 사용 환경에 따라 다릅니다.
2690 2708
2691```text theme={null}2709```text theme={null}
2692There's an issue with the selected model (claude-...). It may not exist or you may not have access to it. Run /model to pick a different model.2710There's an issue with the selected model (claude-...). It may not exist or you may not have access to it. Run /model to pick a different model.
2694 2712
2695**해결 방법:**2713**해결 방법:**
2696 2714
2697* **대화형 CLI**: `/model`을 실행하여 계정에서 사용할 수 있는 모델 중에서 선택하십시오.2715* **대화형 CLI**: `/model`을 실행하여 계정에서 사용할 수 있는 모델 중에서 선택하세요.
2698* **비대화형 모드(`-p`)**: 유효한 별칭 또는 ID와 함께 `--model`을 전달하거나, [`ANTHROPIC_MODEL`](https://code.claude.com/docs/ko/env-vars)을 설정하십시오. 이 사용 환경에서는 오류 텍스트에 `Run --model`이 표시됩니다.2716* **비대화형 모드(`-p`)**: 유효한 별칭이나 ID와 함께 `--model`을 전달하거나 [`ANTHROPIC_MODEL`](https://code.claude.com/docs/ko/env-vars)을 설정하세요. 이 사용 환경에서는 오류 텍스트에 `Run --model`이 표시됩니다.
2699* **Agent SDK**: 모델이 프로그래밍 방식으로 설정되므로 오류 텍스트에 힌트가 생략됩니다. TypeScript에서는 [`Options`의 `model`](https://code.claude.com/docs/ko/agent-sdk/typescript#options)을, Python에서는 [`ClaudeAgentOptions(model=...)`](https://code.claude.com/docs/ko/agent-sdk/python#claudeagentoptions)를 설정하고, 구조화된 `model_not_found` 오류를 처리하여 자체 재시도 또는 모델 선택기를 표시하십시오.2717* **Agent SDK**: 모델이 프로그래밍 방식으로 설정되므로 오류 텍스트에서 힌트가 생략됩니다. TypeScript에서는 [`Options`의 `model`](https://code.claude.com/docs/ko/agent-sdk/typescript#options)을, Python에서는 [`ClaudeAgentOptions(model=...)`](https://code.claude.com/docs/ko/agent-sdk/python#claudeagentoptions)을 설정하고, 구조화된 `model_not_found` 오류를 처리하여 자체 재시도 또는 모델 선택기를 표시하세요.
2700* 전체 버전 ID 대신 `sonnet`이나 `opus` 같은 별칭을 사용하십시오. 별칭은 관리되는 기본값으로 해석되므로 오래되어 쓸모없어지지 않습니다. [모델 구성](https://code.claude.com/docs/ko/model-config.md)을 참조하십시오.2718* 전체 버전 ID 대신 `sonnet` 또는 `opus`와 같은 별칭을 사용하세요. 별칭은 유지 관리되는 기본값으로 확인되므로 오래된 값이 되지 않습니다. [모델 구성](https://code.claude.com/docs/ko/model-config.md)을 참조하세요.
2701* CLI에서 잘못된 모델이 계속 돌아온다면 어딘가에 오래된 ID가 설정되어 있는 것입니다. [우선순위 순서](https://code.claude.com/docs/ko/model-config.md#setting-your-model)대로 모델을 설정할 수 있는 위치를 확인하고 오래된 값을 제거하십시오.2719* CLI에서 잘못된 모델이 계속 다시 나타나면 어딘가에 오래된 ID가 설정되어 있는 것입니다. [우선순위 순서](https://code.claude.com/docs/ko/model-config.md#setting-your-model)에 따라 모델을 설정할 수 있는 위치를 확인하고 오래된 값을 제거하세요.
2702* Claude Code는 만료된 claude.ai 로그인을 이 오류가 아닌 [Login expired](#login-expired)로 보고합니다. v2.1.206 이전에는 더 이상 갱신할 수 없는 만료된 로그인으로 인해 모든 모델이 이 오류로 실패했습니다. 이전 버전에서 이 현상이 나타나면 `/login`을 실행하십시오.2720* Claude Code는 만료된 claude.ai 로그인을 이 오류가 아닌 [Login expired](#login-expired)로 보고합니다. v2.1.206 이전에는 더 이상 갱신할 수 없는 만료된 로그인으로 인해 모든 모델이 이 오류로 실패했습니다. 이전 버전에서 이 현상이 나타나면 `/login`을 실행하세요.
2703* [`ANTHROPIC_BASE_URL`](https://code.claude.com/docs/ko/env-vars)이 [LLM 게이트웨이](https://code.claude.com/docs/ko/llm-gateway)를 가리키고 모든 모델이 이렇게 실패한다면, 게이트웨이와 그 업스트림이 [도구 검색](https://code.claude.com/docs/ko/mcp.md#tool-search-through-a-gateway) 필드를 허용하는지 확인하십시오. 기본적으로 Claude Code는 `defer_loading` 도구 필드와 `tool_reference` 블록을 이를 활성화하는 `anthropic-beta` 헤더와 함께 보냅니다. v2.1.304 이전에는 `ENABLE_TOOL_SEARCH`로 켜지 않는 한 게이트웨이 뒤에서 도구 검색이 꺼져 있었습니다.2721* [`ANTHROPIC_BASE_URL`](https://code.claude.com/docs/ko/env-vars)이 [LLM 게이트웨이](https://code.claude.com/docs/ko/llm-gateway)를 가리키고 모든 모델이 이렇게 실패하면, 게이트웨이와 해당 업스트림이 [도구 검색](https://code.claude.com/docs/ko/mcp.md#tool-search-through-a-gateway) 필드를 허용하는지 확인하세요. 기본적으로 Claude Code는 `defer_loading` 도구 필드와 `tool_reference` 블록을 이를 활성화하는 `anthropic-beta` 헤더와 함께 보냅니다. v2.1.304 이전에는 `ENABLE_TOOL_SEARCH`로 직접 켠 경우를 제외하고 게이트웨이 뒤에서 도구 검색이 꺼져 있었습니다.
2704* Google Cloud의 Agent Platform 배포의 경우 [Google Cloud의 Agent Platform 문제 해결](https://code.claude.com/docs/ko/google-vertex-ai.md#troubleshooting)을 참조하십시오.2722* Google Cloud의 Agent Platform 배포의 경우 [Google Cloud의 Agent Platform 문제 해결](https://code.claude.com/docs/ko/google-vertex-ai.md#troubleshooting)을 참조하세요.
2705 2723
2706### Model is not a recognized model id2724### Model is not a recognized model id
2707 2725
2708모델 전환에 전달한 문자열이 Claude Code가 모델로 사용할 수 있는 것이 아니므로, 요청을 보내지 않고 전환을 거부했으며 세션은 현재 모델을 유지합니다. 이 오류는 [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/typescript.md)의 `setModel()` 메서드로 모델을 설정할 때, [Desktop 앱](https://code.claude.com/docs/ko/desktop.md)처럼 Claude Code CLI를 대신 실행하는 앱이 모델을 설정할 때, 또는 [Remote Control](https://code.claude.com/docs/ko/remote-control.md)로 연결된 기기에서 모델을 선택할 때 발생할 수 있습니다. v2.1.200 이전에는 Claude Code가 해당 문자열을 저장한 후 다음 요청에서 [There's an issue with the selected model](#theres-an-issue-with-the-selected-model)로 실패했습니다.2726모델 전환에 전달한 문자열은 Claude Code가 모델로 사용할 수 있는 문자열이 아니므로, Claude Code는 요청을 보내지 않고 전환을 거부했으며 세션은 현재 모델을 유지합니다. 이 오류는 [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/typescript.md) `setModel()` 메서드나 [Desktop 앱](https://code.claude.com/docs/ko/desktop.md)처럼 Claude Code CLI를 대신 실행하는 앱을 통해 모델을 설정하거나, [Remote Control](https://code.claude.com/docs/ko/remote-control.md)로 연결된 기기에서 모델을 선택할 때 발생할 수 있습니다. v2.1.200 이전에는 Claude Code가 문자열을 저장했다가 다음 요청에서 [There's an issue with the selected model](#theres-an-issue-with-the-selected-model)로 실패했습니다.
2709 2727
2710```text theme={null}2728```text theme={null}
2711Model "Sonnet5" is not a recognized model id. Did you mean 'claude-sonnet-5'?2729Model "Sonnet5" is not a recognized model id. Did you mean 'claude-sonnet-5'?
2712```2730```
2713 2731
2714이 예에서는 앱이 표시 이름 `Sonnet 5`를 보냈으며, 메시지는 이를 공백 없이 반복합니다. 끝부분의 힌트는 가장 가깝게 일치하는 별칭 또는 모델 ID를 표시합니다. 충분히 가까운 것이 없으면 대신 `Run /model to see available models.`로 표시됩니다. [Desktop 앱](https://code.claude.com/docs/ko/desktop.md)이 대신 시작한 세션에서는 일치하는 항목이 없을 때의 힌트가 `Switch to a different model.`로 표시됩니다.2732이 예시에서는 앱이 표시 이름 `Sonnet 5`를 보냈으며, 메시지는 이를 공백 없이 반복합니다. 끝부분의 힌트에는 가장 가깝게 일치하는 별칭 또는 모델 ID가 표시됩니다. 충분히 가까운 항목이 없으면 대신 `Run /model to see available models.`가 표시됩니다. [Desktop 앱](https://code.claude.com/docs/ko/desktop.md)이 대신 시작하는 세션에서는 일치 항목이 없을 때의 힌트가 `Switch to a different model.`로 표시됩니다.
2715 2733
2716Anthropic API에서 Agent SDK나 앱을 통해 전환하는 경우, 표시 이름이나 빈 문자열처럼 모델 ID가 될 수 없는 문자열만 이 오류를 받습니다.2734Anthropic API에서 Agent SDK나 앱을 통해 전환하는 경우, 표시 이름이나 빈 문자열처럼 모델 ID가 될 수 없는 문자열에만 이 오류가 발생합니다.
2717 2735
2718Remote Control 기기에서 모델을 선택하면 Claude Code가 문자열을 로컬에서 확인합니다. 모델 별칭, Claude Code가 나열하거나 사용자가 구성한 모델, 또는 `claude-`로 시작하는 ID가 아닌 모든 문자열은 `claud-sonnet-5`처럼 잘못 입력한 ID를 포함하여 이 오류를 받습니다. v2.1.260 이전에는 이 검사가 Remote Control 선택에 적용되지 않았으므로, 인식되지 않는 문자열이 적용된 후 다음 요청에서 실패했습니다.2736Remote Control 기기에서 모델을 선택하면 Claude Code가 로컬에서 문자열을 확인합니다. 모델 별칭, Claude Code가 나열하거나 사용자가 구성한 모델, 또는 `claude-`로 시작하는 ID가 아닌 모든 문자열에는 이 오류가 발생하며, `claud-sonnet-5`와 같이 잘못 입력한 ID도 포함됩니다. v2.1.260 이전에는 이 검사가 Remote Control 선택에 적용되지 않아, 인식되지 않는 문자열이 적용된 후 다음 요청에서 실패했습니다.
2719 2737
2720**해결 방법:**2738**해결 방법:**
2721 2739
2722* 인수 없이 `/model`을 실행하여 선택기를 열고 계정에서 사용할 수 있는 모델 중에서 선택한 후, 그곳에 표시된 별칭 또는 ID를 전달하십시오2740* 인수 없이 `/model`을 실행하여 선택기를 열고 계정에서 사용할 수 있는 모델 중에서 선택한 다음, 그곳에 표시된 별칭이나 ID를 전달하세요
2723* 최신 Claude Code 버전에서만 지원하는 별칭을 사용했다면 `claude update`를 실행하거나, 대신 모델의 전체 ID를 전달하십시오. 서버는 여전히 해당 모델에 대해 최소 Claude Code 버전을 요구할 수 있습니다. [Claude Code does not support this model](#claude-code-does-not-support-this-model)을 참조하십시오.2741* 최신 Claude Code 버전에서만 지원하는 별칭을 사용한 경우 `claude update`를 실행하거나 대신 모델의 전체 ID를 전달하세요. 서버는 여전히 해당 모델에 대해 최소 Claude Code 버전을 요구할 수 있습니다. [Claude Code does not support this model](#claude-code-does-not-support-this-model)을 참조하세요.
2724* v2.1.200 이전에 저장된 모델은 이 검사로 복구되지 않습니다. 오래된 값이 계속 돌아온다면 [모델 설정](https://code.claude.com/docs/ko/model-config.md#setting-your-model)에 나열된 위치에서 제거하십시오.2742* v2.1.200 이전에 저장된 모델은 이 검사로 복구되지 않습니다. 오래된 값이 계속 다시 나타나면 [모델 설정](https://code.claude.com/docs/ko/model-config.md#setting-your-model)에 나열된 위치에서 제거하세요.
2725* Anthropic API 이외의 제공업체, 또는 게이트웨이나 사용자 지정 `ANTHROPIC_BASE_URL` 뒤에서는 빈 문자열만 이 오류를 받습니다. Claude Code는 모든 제공업체에서 요청 시점에 [인식되지 않는 모델 진단 줄](#unrecognized-model-id-on-a-request)을 여전히 기록할 수 있습니다.2743* Anthropic API 이외의 제공업체나 게이트웨이 또는 사용자 지정 `ANTHROPIC_BASE_URL` 뒤에서는 빈 문자열에만 이 오류가 발생합니다. Claude Code는 모든 제공업체에서 요청 시점에 여전히 [인식되지 않는 모델 진단 줄](#unrecognized-model-id-on-a-request)을 기록할 수 있습니다.
2726 2744
2727### Model not found2745### Model not found
2728 2746
2729이름으로 모델을 전환했지만 Claude Code가 해당 이름의 모델이 존재하는지 확인할 수 없었습니다. 이름이 [모델 별칭](https://code.claude.com/docs/ko/model-config.md#model-aliases)이나 Claude Code가 로컬에서 허용하는 다른 표기가 아니면, Claude Code는 최소한의 API 요청으로 이를 확인하며, 이 오류는 대개 API 엔드포인트의 응답입니다. `/model <name>`의 경우, 공백이 포함된 이름처럼 모델 ID가 전혀 될 수 없는 이름도 같은 메시지를 받습니다.2747이름으로 모델을 전환했지만 Claude Code가 해당 이름의 모델이 존재하는지 확인할 수 없었습니다. 이름이 [모델 별칭](https://code.claude.com/docs/ko/model-config.md#model-aliases)이나 Claude Code가 로컬에서 허용하는 다른 표기가 아니면 Claude Code는 최소한의 API 요청으로 이를 확인하며, 이 오류는 대개 API 엔드포인트의 응답입니다. `/model <name>`에서는 공백이 포함된 이름처럼 애초에 모델 ID가 될 수 없는 이름에도 같은 메시지가 표시됩니다.
2730 2748
2731```text theme={null}2749```text theme={null}
2732Model 'claude-opus-9' not found2750Model 'claude-opus-9' not found
2733```2751```
2734 2752
2735제공업체별 모델 ID를 사용하는 제공업체에서는 메시지에 폴백 모델에 대한 해당 제공업체의 ID를 알려 주는 `Try '...' instead` 제안이 추가될 수 있습니다.2753제공업체별 모델 ID를 사용하는 제공업체에서는 메시지에 대체 모델에 대한 제공업체의 ID를 명시하는 `Try '...' instead` 제안이 추가될 수 있습니다.
2736 2754
2737**해결 방법:**2755**해결 방법:**
2738 2756
2739* 인수 없이 `/model`을 실행하여 계정에서 사용할 수 있는 모델 중에서 선택하거나, 관리되는 기본값으로 해석되는 `sonnet` 같은 [모델 별칭](https://code.claude.com/docs/ko/model-config.md#model-aliases)을 사용하십시오2757* 인수 없이 `/model`을 실행하여 계정에서 사용할 수 있는 모델 중에서 선택하거나, 유지 관리되는 기본값으로 확인되는 `sonnet`과 같은 [모델 별칭](https://code.claude.com/docs/ko/model-config.md#model-aliases)을 사용하세요
2740* 전체 ID를 입력했다면 제공업체의 모델 카탈로그와 대조하여 확인하십시오. 새로 출시된 모델은 제공업체나 리전에서 제공하기 전에 Anthropic API에서 먼저 사용 가능할 수 있습니다.2758* 전체 ID를 입력한 경우 제공업체의 모델 카탈로그와 대조하세요. 새로 출시된 모델은 제공업체나 리전에서 제공되기 전에 Anthropic API에서 먼저 사용 가능할 수 있습니다.
2741* Agent SDK에서는 `setModel()`이 이 메시지와 함께 실패하고 세션은 이전 모델로 계속 실행됩니다. TypeScript SDK에서는 [`supportedModels()`](https://code.claude.com/docs/ko/agent-sdk/typescript#query-object)를 호출하여 전환할 수 있는 모델 목록을 확인하십시오.2759* Agent SDK에서는 `setModel()`이 이 메시지와 함께 실패하고 세션은 이전 모델로 계속 실행됩니다. TypeScript SDK에서는 [`supportedModels()`](https://code.claude.com/docs/ko/agent-sdk/typescript#query-object)를 호출하여 전환할 수 있는 모델 목록을 확인하세요.
2742* v2.1.265 이전에는 `/model`이 `opusplan[1m]` 별칭 표기도 이 오류로 거부했습니다. 해당 버전에서는 Claude Code를 업데이트하거나, 대신 [설정](https://code.claude.com/docs/ko/model-config.md#setting-your-model)에서 또는 `--model`로 모델을 설정하십시오.2760* v2.1.265 이전에는 `/model`이 `opusplan[1m]` 별칭 표기도 이 오류로 거부했습니다. 해당 버전에서는 Claude Code를 업데이트하거나, 대신 [설정](https://code.claude.com/docs/ko/model-config.md#setting-your-model)이나 `--model`로 모델을 설정하세요.
2743 2761
2744### Couldn't confirm model with the API2762### Couldn't confirm model with the API
2745 2763
2746[Agent SDK](https://code.claude.com/docs/ko/agent-sdk/typescript.md)의 `setModel()` 메서드나 [Desktop 앱](https://code.claude.com/docs/ko/desktop.md)처럼 Claude Code CLI를 대신 실행하는 앱을 통해 모델을 전환했으나, API 엔드포인트로 모델 ID를 확인하는 요청이 15초 이내에 응답을 받지 못했습니다. 세션은 현재 모델을 유지합니다.2764[Agent SDK](https://code.claude.com/docs/ko/agent-sdk/typescript.md) `setModel()` 메서드나 [Desktop 앱](https://code.claude.com/docs/ko/desktop.md)처럼 Claude Code CLI를 대신 실행하는 앱을 통해 모델을 전환했는데, API 엔드포인트에서 모델 ID를 확인하는 요청이 15초 내에 응답을 받지 못했습니다. 세션은 현재 모델을 유지합니다.
2747 2765
2748```text theme={null}2766```text theme={null}
2749Couldn't confirm model "claude-sonnet-5" with the API. Try again, or run /model to see available models.2767Couldn't confirm model "claude-sonnet-5" with the API. Try again, or run /model to see available models.
2750```2768```
2751 2769
2752[Desktop 앱](https://code.claude.com/docs/ko/desktop.md)이 대신 시작한 세션에서는 메시지가 `Try again.`으로 끝납니다.2770[Desktop 앱](https://code.claude.com/docs/ko/desktop.md)이 대신 시작하는 세션에서는 메시지가 `Try again.`으로 끝납니다.
2753 2771
2754**해결 방법:**2772**해결 방법:**
2755 2773
2756* 모델로 다시 전환하십시오2774* 해당 모델로 다시 전환하세요
2757* 전환이 계속 실패하면 Claude Code가 API 엔드포인트에 연결할 수 있는지 확인하십시오. [네트워크 및 연결 오류](#network-and-connection-errors)를 참조하십시오2775* 전환이 계속 실패하면 Claude Code가 API 엔드포인트에 연결할 수 있는지 확인하세요. [네트워크 및 연결 오류](#network-and-connection-errors)를 참조하세요
2758 2776
2759### 선택한 모델을 확인할 때 발생하는 API 오류2777### 선택한 모델을 확인할 때 발생하는 API 오류
2760 2778
2761`/model <name>`으로 모델을 선택했거나, 세션에 연결된 앱이 전환을 요청했습니다. API가 속도 제한이나 서버 오류처럼 별도 항목이 없는 이유로 Claude Code가 모델 확인을 위해 보내는 최소한의 요청을 거부했습니다. 세션은 현재 모델을 유지하며, 메시지 끝에 그 사실이 표시됩니다.2779`/model <name>`으로 모델을 선택했거나 세션에 연결된 앱이 전환을 요청했습니다. API가 속도 제한이나 서버 오류처럼 별도 항목이 없는 이유로, Claude Code가 모델을 확인하기 위해 보내는 최소한의 요청을 거부했습니다. 세션은 현재 모델을 유지하며, 메시지 끝에서 이를 알립니다:
2762 2780
2763```text theme={null}2781```text theme={null}
2764API error: 429 <the server's explanation> · model not changed2782API error: 429 <the server's explanation> · model not changed
2768 2786
2769**해결 방법:**2787**해결 방법:**
2770 2788
2771* 서버의 설명에 따라 조치하십시오. 속도 제한이나 5xx 상태의 경우 잠시 기다린 후 모델을 다시 선택하십시오2789* 서버의 설명에 따라 조치하세요. 속도 제한이나 5xx 상태인 경우 잠시 기다린 후 모델을 다시 선택하세요
2772* 고유한 문구가 있는 거부는 [Model not found](#model-not-found)와 [Model is restricted by your organization's settings](#model-is-restricted-by-your-organizations-settings) 같은 주변 항목에서 다룹니다2790* 고유한 문구가 있는 거부는 [Model not found](#model-not-found)와 [Model is restricted by your organization's settings](#model-is-restricted-by-your-organizations-settings) 등 주변 항목에서 다룹니다
2773 2791
2774### Claude Opus is not available with the Claude Pro plan2792### Claude Opus is not available with the Claude Pro plan
2775 2793
2776현재 구독 플랜에 선택한 모델이 포함되어 있지 않습니다.2794활성 구독 플랜에 선택한 모델이 포함되어 있지 않습니다.
2777 2795
2778```text theme={null}2796```text theme={null}
2779Claude Opus is not available with the Claude Pro plan. If you have updated your subscription plan recently, run /logout and /login for the plan to take effect.2797Claude Opus is not available with the Claude Pro plan. If you have updated your subscription plan recently, run /logout and /login for the plan to take effect.
2780```2798```
2781 2799
2782Claude Desktop 앱이 실행하는 세션에서는 메시지가 명령 이름 대신 `sign out and sign in again`이라고 안내합니다.2800Claude Desktop 앱이 실행하는 세션에서는 메시지가 명령 이름을 표시하는 대신 `sign out and sign in again`하라고 안내합니다.
2783 2801
2784**해결 방법:**2802**해결 방법:**
2785 2803
2786* `/model`을 실행하여 플랜에 포함된 모델을 선택하십시오2804* `/model`을 실행하고 플랜에 포함된 모델을 선택하세요
2787* 최근에 플랜을 업그레이드했는데도 이 메시지가 표시된다면 `/logout`을 실행한 후 `/login`을 실행하십시오. 저장된 토큰은 로그인한 시점의 플랜을 반영하므로, claude.ai에서 업그레이드해도 다시 인증하기 전까지는 기존 세션에 적용되지 않습니다.2805* 최근에 플랜을 업그레이드했는데도 이 메시지가 표시되면 `/logout`을 실행한 후 `/login`을 실행하세요. 저장된 토큰은 로그인 시점의 플랜을 반영하므로, claude.ai에서 업그레이드해도 다시 인증하기 전까지는 기존 세션에 적용되지 않습니다.
2788* 각 플랜에 포함된 모델은 [claude.com/pricing](https://claude.com/pricing)을 참조하십시오2806* 각 플랜에 포함된 모델은 [claude.com/pricing](https://claude.com/pricing)을 참조하세요
2789 2807
2790### Claude Code does not support this model2808### Claude Code does not support this model
2791 2809
2792Claude Code 버전이 요구되는 최소 버전보다 낮기 때문에 API가 400으로 요청을 거부했습니다. 선택한 모델이 더 새로운 버전을 요구하거나(서버가 모델별로 확인함), 조직의 정책이 이를 요구하는 경우입니다. 400에는 오류 코드 `claude_code_version_too_old`가 포함되며, 메시지에는 어떤 최소 버전이 적용되는지 표시됩니다.2810Claude Code 버전이 필수 최소 버전보다 낮아 API가 400으로 요청을 거부했습니다. 선택한 모델이 더 새로운 버전을 요구하거나(서버가 모델별로 확인), 조직의 정책이 이를 요구합니다. 400 응답에는 오류 코드 `claude_code_version_too_old`가 포함되며, 메시지에 어떤 최소 버전이 적용되는지 표시됩니다.
2793 2811
2794```text theme={null}2812```text theme={null}
2795API Error: 400 Claude Code 2.1.219 does not support this model; version 2.1.255 or newer is required. Run 'claude update', or update the Claude desktop app, then try again.2813API Error: 400 Claude Code 2.1.219 does not support this model; version 2.1.255 or newer is required. Run 'claude update', or update the Claude desktop app, then try again.
2796```2814```
2797 2815
2798조직 정책 문구는 다음과 같습니다.2816조직 정책 문구는 다음과 같습니다:
2799 2817
2800```text theme={null}2818```text theme={null}
2801API Error: 400 Claude Code 2.1.240 is older than the minimum version required by your organization's policy. Run 'claude update', or update the Claude desktop app, to continue.2819API Error: 400 Claude Code 2.1.240 is older than the minimum version required by your organization's policy. Run 'claude update', or update the Claude desktop app, to continue.
2802```2820```
2803 2821
2804API가 확인하는 버전은 요청을 보낸 Claude Code 바이너리가 보고한 버전입니다.2822API가 확인하는 버전은 요청을 보낸 Claude Code 바이너리가 보고하는 버전입니다.
2805 2823
2806**해결 방법:**2824**해결 방법:**
2807 2825
2808해당 바이너리를 업데이트한 후 새 세션을 시작하십시오. [자체 호스팅 환경](https://code.claude.com/docs/ko/self-hosted-environments-deploy.md#pin-the-version)을 제외하면, 바이너리의 출처에 따라 업데이트 방법이 결정됩니다.2826해당 바이너리를 업데이트한 후 새 세션을 시작하세요. [자체 호스팅 환경](https://code.claude.com/docs/ko/self-hosted-environments-deploy.md#pin-the-version)을 제외하면, 바이너리의 출처에 따라 방법이 달라집니다:
2809 2827
2810| 요청을 보낸 바이너리 | 업데이트 방법 |2828| 요청을 보낸 바이너리 | 업데이트 방법 |
2811| :- | :- |2829| :- | :- |
2812| 직접 설치한 Claude Code | `claude update` 실행 |2830| 직접 설치한 Claude Code | `claude update` 실행 |
2813| Claude desktop 앱 | 앱 업데이트 |2831| Claude 데스크톱 앱 | 앱 업데이트 |
2814| [VS Code 확장 프로그램](https://code.claude.com/docs/ko/vs-code.md)에 번들로 포함된 바이너리 | 확장 프로그램 업데이트 |2832| [VS Code 확장 프로그램](https://code.claude.com/docs/ko/vs-code.md)에 번들된 바이너리 | 확장 프로그램 업데이트 |
2815| Agent SDK 패키지에 번들로 포함된 바이너리 | [SDK 패키지를 업그레이드](https://code.claude.com/docs/ko/agent-sdk/hosting.md#runtime-dependencies)한 후 애플리케이션 재시작. [컴파일된 단일 파일 실행 파일](https://code.claude.com/docs/ko/agent-sdk/typescript.md#compile-to-a-single-executable)의 경우 다시 빌드 |2833| Agent SDK 패키지에 번들된 바이너리 | [SDK 패키지를 업그레이드](https://code.claude.com/docs/ko/agent-sdk/hosting.md#runtime-dependencies)한 후 애플리케이션을 재시작합니다. [컴파일된 단일 파일 실행 파일](https://code.claude.com/docs/ko/agent-sdk/typescript.md#compile-to-a-single-executable)에서는 다시 빌드합니다 |
2816 2834
2817* [stable 릴리스 채널](https://code.claude.com/docs/ko/setup.md#configure-release-channel)에서 `claude update`를 실행하면 최신 stable 릴리스보다 높은 버전으로 이동하지 않으며, 이 릴리스가 여전히 요구되는 최소 버전보다 낮을 수 있습니다. latest 채널로 이동한 후 다시 업데이트하십시오. 조직이 [관리형 설정](https://code.claude.com/docs/ko/managed-settings.md)으로 채널이나 버전을 고정한 경우 관리자에게 변경을 요청하십시오2835* [stable 릴리스 채널](https://code.claude.com/docs/ko/setup.md#configure-release-channel)에서 `claude update`를 실행하면 최신 stable 릴리스보다 새로운 버전으로는 업데이트되지 않으며, 이 릴리스는 여전히 필수 최소 버전보다 낮을 수 있습니다. latest 채널로 이동한 후 다시 업데이트하세요. 조직이 [관리형 설정](https://code.claude.com/docs/ko/managed-settings.md)을 통해 채널이나 버전을 고정한 경우 관리자에게 변경을 요청하세요
2818* 모델별 문구의 경우, 다른 모델로 전환하여 현재 세션에서 계속 작업할 수 있습니다. CLI에서 `/model`을 실행하거나, 스트리밍 입력 모드에서 TypeScript SDK의 `Query` 객체에 대해 [`setModel()`](https://code.claude.com/docs/ko/agent-sdk/typescript#query-object)을 호출하거나, Python SDK의 `ClaudeSDKClient`에 대해 [`set_model()`](https://code.claude.com/docs/ko/agent-sdk/python#claudesdkclient)을 호출하십시오2836* 모델별 문구의 경우 다른 모델로 전환하여 현재 세션에서 계속 작업할 수 있습니다. CLI에서 `/model`을 실행하거나, 스트리밍 입력 모드에서 TypeScript SDK의 `Query` 객체에 대해 [`setModel()`](https://code.claude.com/docs/ko/agent-sdk/typescript#query-object)을 호출하거나, Python SDK의 `ClaudeSDKClient`에 대해 [`set_model()`](https://code.claude.com/docs/ko/agent-sdk/python#claudesdkclient)을 호출하세요
2819* 조직 정책 문구의 경우, 계속하기 전에 업데이트하십시오2837* 조직 정책 문구의 경우 계속하기 전에 업데이트하세요
2820 2838
2821### Model is restricted by your organization's settings2839### Model is restricted by your organization's settings
2822 2840
2823조직 관리자가 claude.ai 관리 콘솔에서 이 모델을 비활성화했거나, 관리형 설정이 [`availableModels`](https://code.claude.com/docs/ko/model-config#restrict-model-selection) 허용 목록 또는 [`deniedModels`](https://code.claude.com/docs/ko/model-config#block-specific-models-or-versions) 목록으로 이 모델을 제외했습니다. 이 알림은 `--model`, `ANTHROPIC_MODEL` 또는 `model` 설정에 제한된 모델이 지정된 경우 시작 시 표시되며, 세션이 대신 사용하는 모델을 알려 줍니다. 관리형 설정으로 인해 세션이 사용할 수 있는 허용된 모델이 없다면 [Managed settings block the default model](#managed-settings-block-the-default-model)을 참조하십시오. 관리자가 claude.ai 관리 콘솔에서 세션이 실행 중인 모델을 비활성화하면, 대체 알림이 세션 도중에도 나타날 수 있습니다.2841조직 관리자가 claude.ai 관리 콘솔에서 이 모델을 비활성화했거나, 관리형 설정이 [`availableModels`](https://code.claude.com/docs/ko/model-config#restrict-model-selection) 허용 목록 또는 [`deniedModels`](https://code.claude.com/docs/ko/model-config#block-specific-models-or-versions) 목록을 통해 이 모델을 제외합니다. 이 알림은 `--model`, `ANTHROPIC_MODEL` 또는 `model` 설정이 제한된 모델을 지정한 경우 시작 시 나타나며, 세션이 대신 사용하는 모델을 명시합니다. 관리형 설정으로 인해 세션이 사용할 수 있는 허용된 모델이 없는 경우 [관리형 설정이 기본 모델을 차단함](#managed-settings-block-the-default-model)을 참조하세요. 관리자가 claude.ai 관리 콘솔에서 세션이 실행 중인 모델을 비활성화하면 대체 알림이 세션 도중에 나타날 수도 있습니다.
2824 2842
2825```text theme={null}2843```text theme={null}
2826Model "claude-opus-4-8" is restricted by your organization's settings. Using claude-sonnet-4-6 instead.2844Model "claude-opus-4-8" is restricted by your organization's settings. Using claude-sonnet-4-6 instead.
2827```2845```
2828 2846
2829제한된 모델에 대해 `/model <name>`을 입력하면 거부되며 세션은 현재 모델을 유지합니다. 관리 콘솔에서 비활성화된 모델의 경우 거부 메시지는 `Model '<name>' is restricted by your organization's settings. Run /model to choose a different model.`입니다. 관리형 설정이 제외한 모델의 경우 `Model '<name>' is not available. Your organization restricts model selection.`입니다.2847제한된 모델에 대해 `/model <name>`을 입력하면 거부되며 세션은 현재 모델을 유지합니다. 관리 콘솔에서 비활성화된 모델의 경우 거부 메시지는 `Model '<name>' is restricted by your organization's settings. Run /model to choose a different model.`입니다. 관리형 설정이 제외하는 모델의 경우 `Model '<name>' is not available. Your organization restricts model selection.`입니다.
2830 2848
2831알림 앞에 에이전트, 스킬 또는 명령 이름이 붙어 있다면 제한이 해당 [서브에이전트가 요청한 모델](https://code.claude.com/docs/ko/sub-agents.md#choose-a-model)에 적용되었다는 의미입니다. 서브에이전트는 대체된 모델로 실행되고 세션의 모델은 변경되지 않습니다. v2.1.223 이전에는 Claude Code가 Agent 도구로 실행된 서브에이전트에 대해서만 알림을 표시했습니다.2849에이전트, 스킬 또는 명령 이름이 앞에 붙은 알림은 해당 [서브에이전트가 요청한 모델](https://code.claude.com/docs/ko/sub-agents.md#choose-a-model)에 제한이 적용되었음을 의미합니다. 서브에이전트는 대체된 모델로 실행되며 세션의 모델은 변경되지 않습니다. v2.1.223 이전에는 Claude Code가 Agent 도구로 시작된 서브에이전트에 대해서만 알림을 표시했습니다.
2832 2850
2833Claude Code는 모델 계열 별칭(`opus`, `sonnet`, `haiku`, `fable` 중 하나)을 최신 버전이 아닌 해당 계열에 대한 요청으로 처리합니다. Anthropic API와 [Claude Platform on AWS](https://code.claude.com/docs/ko/claude-platform-on-aws.md)에서는 제한된 계열 별칭이 조직의 설정이 허용하는 해당 계열의 최신 버전으로 해석되며, 대체 알림에 그 버전이 표시됩니다. Claude Code는 계열의 모든 버전이 제한된 경우에만 `/model <alias>`를 거부합니다. v2.1.205 이전에는 같은 계열의 이전 버전이 허용되더라도 계열 별칭이 최신 버전만을 기준으로 대체되거나 거부되었습니다.2851Claude Code는 `opus`, `sonnet`, `haiku`, `fable` 중 하나인 모델 패밀리 별칭을 해당 패밀리의 최신 버전이 아닌 패밀리 자체에 대한 요청으로 처리합니다. Anthropic API와 [Claude Platform on AWS](https://code.claude.com/docs/ko/claude-platform-on-aws.md)에서 제한된 패밀리 별칭은 조직의 설정이 허용하는 해당 패밀리의 최신 버전으로 확인되며, 대체 알림에 해당 버전이 명시됩니다. Claude Code는 패밀리의 모든 버전이 제한된 경우에만 `/model <alias>`를 거부합니다. v2.1.205 이전에는 같은 패밀리의 이전 버전이 허용되더라도 패밀리 별칭이 최신 버전만을 기준으로 대체되거나 거부되었습니다.
2834 2852
2835**해결 방법:**2853**해결 방법:**
2836 2854
2837* `/model`을 실행하여 조직이 허용하는 모델 중에서 선택하십시오. 제한된 모델은 선택기에서 숨겨집니다.2855* `/model`을 실행하여 조직이 허용하는 모델 중에서 선택하세요. 제한된 모델은 선택기에서 숨겨집니다.
2838* 제한된 모델이 `--model`, `ANTHROPIC_MODEL`, 설정 파일의 `model` 필드, 또는 [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md#choose-a-model), 스킬, 명령의 `model` frontmatter에 설정되어 있다면 알림이 재발하지 않도록 해당 값을 제거하거나 업데이트하십시오2856* 제한된 모델이 `--model`, `ANTHROPIC_MODEL`, 설정 파일의 `model` 필드, 또는 [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md#choose-a-model), 스킬, 명령의 `model` frontmatter에 설정된 경우, 알림이 반복되지 않도록 해당 값을 제거하거나 업데이트하세요
2839* 제한된 모델에 접근해야 한다면 조직 관리자에게 활성화를 요청하십시오. [조직 모델 제한](https://code.claude.com/docs/ko/model-config.md#organization-model-restrictions)을 참조하십시오.2857* 제한된 모델에 액세스해야 하는 경우 조직 관리자에게 활성화를 요청하세요. [조직 모델 제한](https://code.claude.com/docs/ko/model-config.md#organization-model-restrictions)을 참조하세요.
2840 2858
2841### Can't switch to the default model2859### Can't switch to the default model
2842 2860
2843`/model` 선택기에서 Default 행을 선택하거나 `/model default`를 입력하는 등의 방법으로 Default 모델을 선택했습니다. Claude Code가 전환을 거부했으므로 세션은 현재 모델을 유지합니다.2861예를 들어 `/model` 선택기에서 Default 행을 선택하거나 `/model default`를 입력하여 Default 모델을 선택했습니다. Claude Code가 전환을 거부했으므로 세션은 현재 모델을 유지합니다.
2844 2862
2845```text theme={null}2863```text theme={null}
2846Can't switch to the default model: your organization's managed settings block it (claude-opus-4-6) in "deniedModels", and none of the models they allow can be used as the default instead. Ask your administrator to update "deniedModels" or "availableModels".2864Can't switch to the default model: your organization's managed settings block it (claude-opus-4-6) in "deniedModels", and none of the models they allow can be used as the default instead. Ask your administrator to update "deniedModels" or "availableModels".
2847```2865```
2848 2866
2849콜론 뒤의 문구는 무엇이 전환을 막았는지 알려 줍니다.2867콜론 뒤의 문구는 전환을 차단한 원인을 나타냅니다:
2850 2868
2851* **`your organization's managed settings block it ... in "deniedModels"`**: 관리형 거부 목록이 Default 옵션이 해석되는 모델을 차단합니다2869* **`your organization's managed settings block it ... in "deniedModels"`**: 관리형 거부 목록이 Default 옵션이 확인되는 모델을 차단합니다
2852* **`your organization allows only the models listed in "availableModels"`**: [`availableModelsMatch`](https://code.claude.com/docs/ko/settings-reference#availablemodelsmatch)가 `"exact"`로 설정된 관리형 [`availableModels`](https://code.claude.com/docs/ko/model-config#restrict-model-selection) 허용 목록에 Default 옵션이 해석되는 모델이 포함되어 있지 않습니다2870* **`your organization allows only the models listed in "availableModels"`**: [`availableModelsMatch`](https://code.claude.com/docs/ko/settings-reference#availablemodelsmatch)가 `"exact"`로 설정된 관리형 [`availableModels`](https://code.claude.com/docs/ko/model-config#restrict-model-selection) 허용 목록에 Default 옵션이 확인되는 모델이 포함되어 있지 않습니다
2853* **`Claude Code couldn't read your organization's managed settings to check which models they allow`**: [관리형 설정](https://code.claude.com/docs/ko/managed-settings.md)을 읽을 수 없었으며, Claude Code는 확인 없이 전환을 적용하는 대신 전환을 거부합니다2871* **`Claude Code couldn't read your organization's managed settings to check which models they allow`**: [관리형 설정](https://code.claude.com/docs/ko/managed-settings.md)을 읽을 수 없었으며, Claude Code는 확인되지 않은 상태로 전환을 적용하는 대신 전환을 거부합니다
2854 2872
2855**해결 방법:**2873**해결 방법:**
2856 2874
2857* [`deniedModels`](https://code.claude.com/docs/ko/settings-reference#deniedmodels) 및 `availableModels` 문구의 경우, `/model`을 실행하고 조직이 허용하는 모델을 이름으로 선택하십시오2875* [`deniedModels`](https://code.claude.com/docs/ko/settings-reference#deniedmodels) 및 `availableModels` 문구의 경우 `/model`을 실행하고 조직이 허용하는 모델을 이름으로 선택하세요
2858* 관리자에게 메시지에 표시된 관리형 설정을 업데이트해 달라고 요청하십시오2876* 메시지에 명시된 관리형 설정을 업데이트하도록 관리자에게 요청하세요
2859* `couldn't read` 문구의 경우 Claude Code를 재시작하십시오. 계속 발생한다면 관리자에게 관리형 설정을 확인해 달라고 요청하십시오2877* `couldn't read` 문구의 경우 Claude Code를 재시작하세요. 계속 발생하면 관리자에게 관리형 설정을 확인하도록 요청하세요
2860 2878
2861대신 이러한 관리형 설정에서 `Claude Code can't start` 메시지와 함께 세션 시작이 실패한다면 [Managed settings block the default model](#managed-settings-block-the-default-model)을 참조하십시오.2879이러한 관리형 설정에서 대신 `Claude Code can't start` 메시지와 함께 세션이 시작되지 않으면 [관리형 설정이 기본 모델을 차단함](#managed-settings-block-the-default-model)을 참조하세요.
2862 2880
2863### Model switch was blocked by a PreModelSwitch hook2881### Model switch was blocked by a PreModelSwitch hook
2864 2882
2865[PreModelSwitch 훅](https://code.claude.com/docs/ko/hooks.md#premodelswitch)이 사용자 또는 클라이언트가 요청한 모델 전환을 승인하지 않았으므로 세션은 현재 모델을 유지합니다. 입력한 명령이 아니라 [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/overview.md) 호스트나 [Remote Control](https://code.claude.com/docs/ko/remote-control.md)에서 전환이 요청된 경우, 메시지는 대상 모델을 명시하지 않고 `Model switch blocked by a PreModelSwitch hook`으로 표시됩니다.2883[PreModelSwitch 훅](https://code.claude.com/docs/ko/hooks.md#premodelswitch)이 사용자나 클라이언트가 요청한 모델 전환을 승인하지 않아 세션이 현재 모델을 유지합니다. 직접 입력한 명령이 아닌 [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/overview.md) 호스트나 [Remote Control](https://code.claude.com/docs/ko/remote-control.md)에서 전환이 시작된 경우, 메시지는 대상 모델을 명시하지 않고 `Model switch blocked by a PreModelSwitch hook`으로 표시됩니다.
2866 2884
2867```text theme={null}2885```text theme={null}
2868Model switch to Opus 4.6 was blocked by a PreModelSwitch hook: Opus 4.6 is retired for this project. Use a newer model.2886Model switch to Opus 4.6 was blocked by a PreModelSwitch hook: Opus 4.6 is retired for this project. Use a newer model.
2869```2887```
2870 2888
2871콜론 뒤의 이유는 무엇이 전환을 거부했는지 알려 줍니다.2889콜론 뒤의 이유는 무엇이 전환을 거부했는지 나타냅니다:
2872 2890
2873* **훅이 작성한 이유**: PreModelSwitch 훅이 [전환을 거부하거나 확인을 요청](https://code.claude.com/docs/ko/hooks.md#premodelswitch-decision-control)할 때 해당 이유를 제공했습니다. 요청 사항을 해결하거나, 훅이 허용하는 모델을 선택하십시오.2891* **훅이 작성한 이유**: PreModelSwitch 훅이 [전환을 거부하거나 확인을 요청](https://code.claude.com/docs/ko/hooks.md#premodelswitch-decision-control)할 때 해당 이유를 제공했습니다. 요청된 내용을 해결하거나 훅이 허용하는 모델을 선택하세요.
2874* **`PreModelSwitch hook <name> did not respond before its timeout`**: [타임아웃](https://code.claude.com/docs/ko/hooks.md#timeouts) 전에 응답하지 않는 훅은 전환을 차단합니다. 멈춘 명령을 수정하거나 해당 훅의 `timeout`을 늘린 후 다시 전환하십시오.2892* **`PreModelSwitch hook <name> did not respond before its timeout`**: [타임아웃](https://code.claude.com/docs/ko/hooks.md#timeouts) 전에 응답하지 않는 훅은 전환을 차단합니다. 멈춘 명령을 수정하거나 해당 훅의 `timeout`을 늘린 후 다시 전환하세요.
2875* **`confirmation required, and this session cannot ask`**: 훅이 이유 없이 `ask`로 응답했으며, 제어 요청에는 확인 프롬프트를 표시할 방법이 없습니다. [`-p` 실행](https://code.claude.com/docs/ko/headless)에서 `/model` 명령은 이유 뒤에 `(run /model interactively to confirm)`을 붙여 같은 상태를 보고합니다. 대화형 세션에서 전환하거나, 이 모델에 대한 훅의 결정을 변경하십시오.2893* **`confirmation required, and this session cannot ask`**: 훅이 이유 없이 `ask`로 응답했으며, 제어 요청에는 확인 프롬프트를 표시할 방법이 없습니다. [`-p` 실행](https://code.claude.com/docs/ko/headless)의 `/model` 명령은 같은 상태를 이유 뒤에 `(run /model interactively to confirm)`을 붙여 보고합니다. 대화형 세션에서 전환하거나 이 모델에 대한 훅의 결정을 변경하세요.
2876* **`so organization-managed PreModelSwitch hooks could not be checked`**: 관리형 플러그인 로드 실패 등의 이유로, Claude Code가 조직의 [관리형 플러그인](https://code.claude.com/docs/ko/settings-reference.md#enabledplugins)이 제공하는 PreModelSwitch 훅을 파악할 수 없었습니다. 이러한 훅 중 하나가 전환을 차단할 수 있으므로, Claude Code는 확인 없이 전환을 적용하는 대신 거부합니다. 이유의 시작 부분에 무엇이 실패했는지 표시됩니다. Claude Code는 전환을 시도할 때마다 다시 확인하므로, 이후 해결된 실패는 더 이상 차단하지 않습니다. 계속 실패한다면 `claude --debug`를 실행하고 다시 전환하여 세부 정보를 캡처한 후, 플러그인을 수정하거나 관리자에게 수정을 요청하십시오.2894* **`so organization-managed PreModelSwitch hooks could not be checked`**: v2.1.323 이전의 Claude Code는 [관리형 플러그인](https://code.claude.com/docs/ko/settings-reference.md#enabledplugins)이 제공하는 PreModelSwitch 훅을 파악할 수 없으면 전환을 거부합니다. 이 문구 앞의 텍스트는 무엇이 실패했는지 나타냅니다. 거부를 멈추려면 Claude Code를 업데이트하세요. 실패한 플러그인의 훅도 실행되도록 하려면 플러그인을 수정하거나 관리자에게 문의하세요. 자세한 내용을 확인하려면 셸에서 `claude --debug`를 시작하고 모델을 전환한 다음 [디버그 로그](https://code.claude.com/docs/ko/hooks.md#debug-hooks)를 읽으세요.
2877* **`a PreModelSwitch hook failed before answering`** 또는 **`PreModelSwitch hooks were cancelled (the control stream closed) before answering`**: 훅 실행이 판정 없이 종료되었으며, Claude Code는 이를 승인으로 처리하지 않습니다. `claude --debug`를 실행하여 무엇이 실패했는지 확인한 후 다시 전환하십시오.2895* **`a PreModelSwitch hook failed before answering`** 또는 **`PreModelSwitch hooks were cancelled (the control stream closed) before answering`**: 훅 실행이 결정 없이 종료되었으며, Claude Code는 이를 승인으로 간주하지 않습니다. `claude --debug`를 실행하여 무엇이 실패했는지 확인한 후 다시 전환하세요.
2878 2896
2879v2.1.260 이전에는 관리형 플러그인 거부 메시지가 `plugin hooks could not be loaded, so PreModelSwitch hooks could not be checked; see the debug log`였습니다. Claude Code는 플러그인 로드를 한 번 재시도한 후, 조직이 관리하는 플러그인이 없더라도 세션에서 이후의 전환을 거부했습니다. 해당 버전에서는 세션을 재시작하여 플러그인 로드를 다시 실행하십시오.2897v2.1.260 이전에는 관리형 플러그인 거부 문구가 `plugin hooks could not be loaded, so PreModelSwitch hooks could not be checked; see the debug log`였습니다. Claude Code는 플러그인 로드를 한 번 재시도한 후, 조직이 관리하는 플러그인이 없는 경우에도 세션에서 이후의 전환을 거부했습니다. 해당 버전에서는 세션을 재시작하여 플러그인 로드를 다시 실행하세요.
2880 2898
2881### Couldn't save it as your default2899### Couldn't save it as your default
2882 2900
2883`/model <name>`이나 `/model` 선택기의 `Enter` 등으로 기본값으로 저장할 모델을 선택했지만, Claude Code가 선택 내용을 사용자 설정 파일 `~/.claude/settings.json`에 기록하지 못했습니다. 전환 자체는 적용되었으므로 현재 세션은 선택한 모델로 실행되지만, 기본값은 변경되지 않았으며 다음 세션은 이전 값으로 시작됩니다.2901예를 들어 `/model <name>` 또는 `/model` 선택기에서 `Enter`로 기본값으로 저장할 모델을 선택했지만, Claude Code가 선택 내용을 사용자 설정 파일인 `~/.claude/settings.json`에 기록하지 못했습니다. 전환 자체는 적용되었으므로 현재 세션은 선택한 모델로 실행되지만, 기본값은 변경되지 않았으며 다음 세션은 이전 값으로 시작합니다.
2884 2902
2885```text theme={null}2903```text theme={null}
2886Set model to Fable 5.1 for this session only · couldn't save it as your default: ~/.claude/settings.json can't be written (EROFS)2904Set model to Fable 5.1 for this session only · couldn't save it as your default: ~/.claude/settings.json can't be written (EROFS)
2887```2905```
2888 2906
2889파일 경로 뒤의 이유는 무엇이 실패했는지 알려 줍니다.2907파일 경로 뒤의 이유는 무엇이 실패했는지 나타냅니다:
2890 2908
2891* **`can't be written (<code>)`**: 괄호 안의 운영 체제 오류 코드와 함께 쓰기가 실패했습니다. 예를 들어 파일 또는 파일이 링크하는 대상이 쓰기를 거부하는 파일 시스템에 있으면 `EROFS`가 표시됩니다. 파일을 쓰기 가능하게 만든 후 다시 전환하십시오. 다른 도구가 파일을 생성한다면 대신 해당 도구에서 `model` 키를 설정하십시오. [Claude Code에서 변경한 내용이 새 세션에서 사라지는 경우](https://code.claude.com/docs/ko/settings.md#a-change-you-made-in-claude-code-is-lost-in-new-sessions)를 참조하십시오.2909* **`can't be written (<code>)`**: 쓰기가 괄호 안의 운영 체제 오류 코드와 함께 실패했습니다. 예를 들어 파일 또는 파일이 링크하는 대상 파일이 쓰기를 거부하는 파일 시스템에 있으면 `EROFS`가 표시됩니다. 파일을 쓰기 가능하게 만든 후 다시 전환하세요. 다른 도구가 파일을 생성하는 경우 대신 해당 도구에서 `model` 키를 설정하세요. [Claude Code에서 변경한 내용이 새 세션에서 사라짐](https://code.claude.com/docs/ko/settings.md#a-change-you-made-in-claude-code-is-lost-in-new-sessions)을 참조하세요.
2892* **`isn't valid JSON`**: 디스크의 파일을 파싱할 수 없으며, Claude Code는 다시 읽을 수 없는 내용을 덮어쓰는 대신 파일을 그대로 둡니다. 구문 오류를 수정한 후 다시 전환하십시오. [손상된 설정 파일 수정](https://code.claude.com/docs/ko/settings.md#fix-a-broken-settings-file)을 참조하십시오.2910* **`isn't valid JSON`**: 디스크의 파일을 파싱할 수 없으며, Claude Code는 다시 읽을 수 없는 내용을 덮어쓰지 않도록 파일을 그대로 둡니다. 구문 오류를 수정한 후 다시 전환하세요. [손상된 설정 파일 수정](https://code.claude.com/docs/ko/settings.md#fix-a-broken-settings-file)을 참조하세요.
2893 2911
2894`couldn't confirm it was saved as your default (~/.claude/settings.json is still being written)`로 끝나는 알림은 3초가 지나도 쓰기가 완료되지 않았다는 의미입니다. 쓰기는 백그라운드에서 계속되므로 기본값이 여전히 저장될 수 있습니다. 다음 세션이 어떤 모델로 시작되는지 확인하거나, `/model <name>`을 다시 실행하십시오.2912`couldn't confirm it was saved as your default (~/.claude/settings.json is still being written)`로 끝나는 알림은 3초가 지난 후에도 쓰기가 완료되지 않았음을 의미합니다. 쓰기는 백그라운드에서 계속되므로 기본값이 여전히 저장될 수 있습니다. 다음 세션이 어떤 모델로 시작하는지 확인하거나 `/model <name>`을 다시 실행하세요.
2895 2913
2896v2.1.265 이전에는 쓰기가 실패한 경우에도 알림에 모델이 `saved as your default for new sessions`라고 표시되었습니다.2914v2.1.265 이전에는 쓰기가 실패한 경우에도 알림에 모델이 `saved as your default for new sessions`되었다고 표시되었습니다.
2897 2915
2898### Advisor is less capable than the current main model2916### Advisor is less capable than the current main model
2899 2917
2900[advisor 모델](https://code.claude.com/docs/ko/advisor.md)의 순위가 세션의 메인 모델보다 낮으므로, Claude Code는 선택을 유지하지만 메인 모델의 요청에 advisor를 연결하지 않습니다.2918[어드바이저 모델](https://code.claude.com/docs/ko/advisor.md)의 순위가 세션의 메인 모델보다 낮으므로, Claude Code는 선택은 유지하지만 메인 모델의 요청에 어드바이저를 연결하지 않습니다.
2901 2919
2902```text theme={null}2920```text theme={null}
2903Advisor set to Opus 4.82921Advisor set to Opus 4.8
2904Note: Opus 4.8 is less capable than the current main model (Sonnet 5.5), so the advisor will not activate. Choose a more capable advisor, or switch to a smaller main model.2922Note: Opus 4.8 is less capable than the current main model (Sonnet 5.5), so the advisor will not activate. Choose a more capable advisor, or switch to a smaller main model.
2905```2923```
2906 2924
2907다른 메시지도 같은 상태를 보고합니다.2925다른 메시지도 같은 상태를 보고합니다:
2908 2926
2909* 대화형 세션에서는 `Advisor will not activate on the main model (advisor is less capable); subagents may still use it and may use more tokens · /advisor`라는 알림이 표시됩니다.2927* 대화형 세션에서는 `Advisor will not activate on the main model (advisor is less capable); subagents may still use it and may use more tokens · /advisor`라는 알림이 표시됩니다.
2910* [비대화형 모드](https://code.claude.com/docs/ko/headless.md)에서 `--advisor` 플래그로 실행하고 해당 실행이 [백그라운드 세션](https://code.claude.com/docs/ko/agent-view.md)이 아닌 경우, stderr에 경고가 출력되고 실행은 그대로 시작됩니다. 경고 내용은 `"<advisor>" cannot advise "<main model>" (the advisor must be at least as capable as the main model). The advisor will not be used for the main model.`입니다. 대화형 세션은 이 경고를 [디버그 로그](#configuration-warnings)에만 기록합니다.2928* [비대화형 모드](https://code.claude.com/docs/ko/headless.md)에서 `--advisor` 플래그로 실행하고 해당 실행이 [백그라운드 세션](https://code.claude.com/docs/ko/agent-view.md)이 아닌 경우, 경고가 stderr로 출력되고 실행은 그대로 시작됩니다. 경고 내용은 `"<advisor>" cannot advise "<main model>" (the advisor must be at least as capable as the main model). The advisor will not be used for the main model.`입니다. 대화형 세션은 이 경고를 [디버그 로그](#configuration-warnings)에만 기록합니다.
2911 2929
2912**해결 방법:**2930**해결 방법:**
2913 2931
2914* 순위가 더 높은 advisor나 순위가 더 낮은 메인 모델을 선택하십시오. [advisor 모델 선택](https://code.claude.com/docs/ko/advisor.md#choose-an-advisor-model)에서 순위를 확인하고 각 메인 모델에 허용되는 advisor 목록을 볼 수 있습니다.2932* 순위가 더 높은 어드바이저나 순위가 더 낮은 메인 모델을 선택하세요. [어드바이저 모델 선택](https://code.claude.com/docs/ko/advisor.md#choose-an-advisor-model)에서 순위를 보여 주고 각 메인 모델에 허용되는 어드바이저를 나열합니다.
2915* advisor가 자문할 수 있는 모델을 사용하는 [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md)가 계속 advisor를 사용하게 하려면 advisor를 설정된 상태로 두십시오2933* 어드바이저가 자문할 수 있는 모델을 사용하는 [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md)가 계속 어드바이저를 사용하도록 하려면 어드바이저 설정을 그대로 두세요
2916 2934
2917v2.1.287 이전에는 Claude Code가 여러 조합의 순위를 다르게 매겼습니다. Opus 4.7 또는 Opus 4.8 메인 모델에 Sonnet 5.5 advisor를 조합한 경우 이 안내를 표시했지만, 이제는 이 조합을 허용합니다. 또한 Sonnet 5.5 메인 모델에 Opus 4.8 advisor를 조합한 경우처럼, 현재는 이 안내가 표시되는 일부 advisor를 연결했습니다.2935v2.1.287 이전에는 Claude Code가 여러 조합의 순위를 다르게 매겼습니다. Opus 4.7 또는 Opus 4.8 메인 모델과 Sonnet 5.5 어드바이저 조합에 이 참고 사항을 표시했지만, 현재는 이 조합을 허용합니다. 또한 Sonnet 5.5 메인 모델과 Opus 4.8 어드바이저 조합처럼 현재는 이 참고 사항이 표시되는 일부 어드바이저를 연결했습니다.
2918 2936
2919### thinking.type.enabled is not supported for this model2937### thinking.type.enabled is not supported for this model
2920 2938
2921Claude Code 버전이 선택한 모델의 최소 버전보다 오래되었습니다. CLI가 모델이 더 이상 허용하지 않는 사고 구성을 보냈습니다.2939Claude Code 버전이 선택한 모델에 필요한 최소 버전보다 오래되었습니다. CLI가 모델이 더 이상 허용하지 않는 사고 구성을 보냈습니다.
2922 2940
2923```text theme={null}2941```text theme={null}
2924API Error: 400 ... "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.2942API Error: 400 ... "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.
2926 2944
2927**해결 방법:**2945**해결 방법:**
2928 2946
2929* `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 이상이 필요합니다2947* `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 이상이 필요합니다
2930* [stable 릴리스 채널](https://code.claude.com/docs/ko/setup.md#configure-release-channel)에서는 업데이트해도 최신 stable 릴리스보다 높은 버전으로 이동하지 않으며, 이 릴리스가 여전히 위 버전보다 오래되었을 수 있습니다. latest 채널로 이동한 후 업데이트하십시오2948* [stable 릴리스 채널](https://code.claude.com/docs/ko/setup.md#configure-release-channel)에서는 업데이트해도 최신 stable 릴리스보다 새로운 버전으로 이동하지 않으며, 이 릴리스는 여전히 이러한 버전보다 오래되었을 수 있습니다. latest 채널로 이동한 후 업데이트하세요
2931* 업그레이드할 수 없다면 `/model`을 실행하고 대신 Opus 4.6 또는 Sonnet 4.6을 선택하십시오2949* 업그레이드할 수 없으면 `/model`을 실행하고 대신 Opus 4.6 또는 Sonnet 4.6을 선택하세요
2932* [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/overview.md)에서 이 문제가 발생한다면 대신 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 이상이 필요합니다2950* [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/overview.md)에서 이 문제가 발생하면 대신 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 이상이 필요합니다
2933 2951
2934### Effort isn't available with thinking turned off2952### Effort isn't available with thinking turned off
2935 2953
2936[확장 사고](https://code.claude.com/docs/ko/model-config.md#extended-thinking)를 끄고 `high`보다 높은 [effort 수준](https://code.claude.com/docs/ko/model-config.md#adjust-effort-level)으로 실행했습니다. 모델이 이 조합을 허용하지 않으므로 API가 요청을 거부했습니다.2954[확장 사고](https://code.claude.com/docs/ko/model-config.md#extended-thinking)를 끈 상태에서 `high`보다 높은 [effort 수준](https://code.claude.com/docs/ko/model-config.md#adjust-effort-level)으로 실행했습니다. 모델이 이 조합을 허용하지 않으므로 API가 요청을 거부했습니다.
2937 2955
2938```text theme={null}2956```text theme={null}
2939API 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)2957API 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)
2943 2961
2944**해결 방법:**2962**해결 방법:**
2945 2963
2946* [effort 수준을 낮추어](https://code.claude.com/docs/ko/model-config.md#set-the-effort-level) `high` 이하로 설정하십시오.2964* [effort 수준을 낮춰](https://code.claude.com/docs/ko/model-config.md#set-the-effort-level) `high` 이하로 설정하세요.
2947* 예를 들어 [`MAX_THINKING_TOKENS`](https://code.claude.com/docs/ko/env-vars) 설정을 해제하거나 설정에서 [`"alwaysThinkingEnabled": false`](https://code.claude.com/docs/ko/settings-reference#alwaysthinkingenabled)를 제거하여 사고를 다시 켜십시오.2965* 예를 들어 [`MAX_THINKING_TOKENS`](https://code.claude.com/docs/ko/env-vars) 설정을 해제하거나 설정에서 [`"alwaysThinkingEnabled": false`](https://code.claude.com/docs/ko/settings-reference#alwaysthinkingenabled)를 제거하여 사고를 다시 켜세요.
2948 2966
2949v2.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`로 요청을 보냅니다.2967v2.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`를 보냅니다.
2950 2968
2951### 사고 예산이 출력 한도를 초과함2969### 사고 예산이 출력 한도를 초과함
2952 2970
2953구성된 확장 사고 예산이 최대 응답 길이를 초과하여 실제 답변을 위한 공간이 남지 않았습니다.2971구성된 확장 사고 예산이 최대 응답 길이를 초과하여 실제 답변을 위한 공간이 남지 않습니다.
2954 2972
2955```text theme={null}2973```text theme={null}
2956API Error: 400 ... max_tokens must be greater than thinking.budget_tokens2974API Error: 400 ... max_tokens must be greater than thinking.budget_tokens
2958 2976
2959**해결 방법:**2977**해결 방법:**
2960 2978
2961* [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](https://code.claude.com/docs/ko/env-vars)를 사고 예산보다 높게 설정하십시오2979* [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](https://code.claude.com/docs/ko/env-vars)를 사고 예산보다 높게 올리세요
2962* 예산이 출력 길이와 어떻게 상호작용하는지는 [확장 사고](https://code.claude.com/docs/ko/model-config.md#extended-thinking)를 참조하십시오2980* 예산이 출력 길이와 어떻게 상호 작용하는지는 [확장 사고](https://code.claude.com/docs/ko/model-config.md#extended-thinking)를 참조하세요
2963 2981
2964### Response exceeded the output token maximum2982### Response exceeded the output token maximum
2965 2983
2966Claude의 응답이 요청에서 허용하는 최대 출력 토큰 수에 도달하여 그 지점에서 잘렸습니다.2984Claude의 응답이 요청에서 허용하는 최대 출력 토큰 수에 도달하여 그 지점에서 잘렸습니다:
2967 2985
2968```text theme={null}2986```text theme={null}
2969API Error: Claude's response exceeded the ... output token maximum. To configure this behavior, set the CLAUDE_CODE_MAX_OUTPUT_TOKENS environment variable.2987API Error: Claude's response exceeded the ... output token maximum. To configure this behavior, set the CLAUDE_CODE_MAX_OUTPUT_TOKENS environment variable.
2970API Error: Claude's response exceeded the 64000 output token maximum for a request sent without streaming. The CLAUDE_CODE_MAX_OUTPUT_TOKENS environment variable cannot raise this limit.2988API Error: Claude's response exceeded the 64000 output token maximum for a request sent without streaming. The CLAUDE_CODE_MAX_OUTPUT_TOKENS environment variable cannot raise this limit.
2971```2989```
2972 2990
2973`a request sent without streaming`이 표시된 형식은 스트리밍 요청이 실패하여 Claude Code가 스트리밍 없이 다시 보냈다는 의미이며, 이 경우 응답이 64,000 출력 토큰으로 제한됩니다. v2.1.299 이전에는 이렇게 다시 보낸 요청에서 응답이 잘리면, 이 메시지 없이 응답이 완료된 것처럼 턴이 종료되었습니다.2991`a request sent without streaming`을 명시하는 형식은 스트리밍 요청이 실패하여 Claude Code가 스트리밍 없이 다시 보냈다는 의미이며, 이 경우 응답은 64,000 출력 토큰으로 제한됩니다. v2.1.299 이전에는 이렇게 다시 보낸 요청에서 응답이 잘리면 이 메시지 없이 응답이 완료된 것처럼 턴이 종료되었습니다.
2974 2992
2975**해결 방법:**2993**해결 방법:**
2976 2994
2977* 응답이 잘리기 전에 Claude가 일부 텍스트를 작성했다면, 대화형 세션에서 `continue`로 답하여 나머지를 요청하십시오. 해당 텍스트는 대화에 남아 있습니다.2995* 응답이 잘리기 전에 Claude가 일부 텍스트를 작성했다면, 대화형 세션에서 `continue`로 답하여 나머지를 요청하세요. 해당 텍스트는 대화에 남아 있습니다.
2978* 메시지에서 `CLAUDE_CODE_MAX_OUTPUT_TOKENS`를 설정하라고 안내한다면, 값의 상한이 정해지는 방식은 [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](https://code.claude.com/docs/ko/env-vars)를, 설정 위치는 [환경 변수 설정](https://code.claude.com/docs/ko/env-vars.md#set-environment-variables)을 참조하십시오2996* 메시지에서 `CLAUDE_CODE_MAX_OUTPUT_TOKENS`를 설정하라고 안내하면, 값의 상한이 어떻게 정해지는지는 [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](https://code.claude.com/docs/ko/env-vars)를, 설정 위치는 [환경 변수 설정](https://code.claude.com/docs/ko/env-vars.md#set-environment-variables)을 참조하세요
2979* 각 응답이 한도를 넘지 않도록, 응답마다 파일 하나 또는 섹션 하나처럼 더 작은 단위로 출력을 요청하십시오2997* 각 응답을 한도 이내로 유지하려면 응답당 파일 하나 또는 섹션 하나처럼 더 작은 단위로 출력을 요청하세요
2980 2998
2981### 도구 사용 또는 thinking 블록 불일치2999### 도구 사용 또는 thinking 블록 불일치
2982 3000
2990API Error: 400 ... thinking blocks ... cannot be modified3008API Error: 400 ... thinking blocks ... cannot be modified
2991```3009```
2992 3010
2993모든 변형은 같은 의미입니다. 기록에 있는 `tool_use`, `tool_result`, `thinking` 블록의 순서가 더 이상 API가 기대하는 것과 일치하지 않습니다.3011모든 변형은 같은 의미입니다. 기록의 `tool_use`, `tool_result`, `thinking` 블록 순서가 더 이상 API가 예상하는 것과 일치하지 않습니다.
2994 3012
2995**해결 방법:**3013**해결 방법:**
2996 3014
2997* Opus 4.7 또는 Opus 4.8을 사용 중이라면 먼저 `claude update`를 실행하십시오. v2.1.156 이전 버전은 일반적인 도구 사용 중에 이 오류를 일으킬 수 있으며, `/rewind`로는 해결되지 않습니다.3015* Opus 4.7 또는 Opus 4.8을 사용하는 경우 먼저 `claude update`를 실행하세요. v2.1.156 이전 버전은 일반적인 도구 사용 중에 이 오류를 일으킬 수 있으며, `/rewind`로는 해결되지 않습니다.
2998* `/rewind`를 실행하거나 Esc를 두 번 눌러 손상된 턴 이전의 체크포인트로 되돌아간 후 그곳에서 계속하십시오. 체크포인트가 생성되고 복원되는 방식은 [체크포인트](https://code.claude.com/docs/ko/checkpointing.md)를 참조하십시오.3016* `/rewind`를 실행하거나 Esc를 두 번 눌러 손상된 턴 이전의 체크포인트로 돌아간 후 그곳에서부터 계속하세요. 체크포인트가 생성되고 복원되는 방식은 [체크포인트](https://code.claude.com/docs/ko/checkpointing.md)를 참조하세요.
2999 3017
3000### Invalid data in redacted\_thinking block3018### Invalid data in redacted\_thinking block
3001 3019
3002대화 기록의 이전 턴에 포함된 `redacted_thinking` 블록을 허용할 수 없었기 때문에 API가 400으로 요청을 거부했습니다.3020API가 대화 기록의 이전 턴에 포함된 `redacted_thinking` 블록을 허용할 수 없어 400으로 요청을 거부했습니다.
3003 3021
3004```text theme={null}3022```text theme={null}
3005API Error: 400 ... Invalid `data` in `redacted_thinking` block3023API Error: 400 ... Invalid `data` in `redacted_thinking` block
3006```3024```
3007 3025
3008Claude Code는 대화의 이전 사고를 요청에서 제외하고 한 번 재시도하므로, 세션은 오류를 표시하지 않고 계속됩니다. v2.1.282 이전에는 Claude Code가 거부된 블록을 유지했기 때문에 이후의 모든 턴이 같은 오류로 실패했습니다.3026Claude Code는 대화의 이전 사고 내용을 요청에서 제외하고 한 번 재시도하므로, 세션은 오류를 표시하지 않고 계속됩니다. v2.1.282 이전에는 Claude Code가 거부된 블록을 유지했기 때문에 이후의 모든 턴이 같은 오류로 실패했습니다.
3009 3027
3010**해결 방법:**3028**해결 방법:**
3011 3029
3012* v2.1.281 이하 버전을 사용 중이고 모든 턴이 이 오류로 실패한다면 `claude update`를 실행하고 세션을 재개하십시오3030* v2.1.281 이하를 사용 중이고 모든 턴이 이 오류로 실패하면 `claude update`를 실행하고 세션을 재개하세요
3013* 오류가 지속되면 `/clear`를 실행하여 해당 블록이 포함되지 않은 대화를 시작하십시오3031* 오류가 지속되면 `/clear`를 실행하여 해당 블록이 포함되지 않은 대화를 시작하세요
3014 3032
3015### Unsupported tool content removed3033### Unsupported tool content removed
3016 3034
3017Claude Code가 Anthropic API에 직접 연결하여 저장된 세션을 로드하거나 미리 볼 때, Anthropic API가 허용하지 않는 도구 콘텐츠를 제거하고, 제거된 콘텐츠가 두 thinking 블록 사이에 있던 위치에 다음 줄을 남깁니다.3035Claude Code가 Anthropic API에 직접 연결된 상태에서 저장된 세션을 로드하거나 미리 볼 때, Anthropic API가 허용하지 않는 도구 콘텐츠를 제거하고, 제거된 콘텐츠가 두 thinking 블록 사이에 있던 자리에 다음 줄을 남깁니다:
3018 3036
3019```text theme={null}3037```text theme={null}
3020[Unsupported tool content removed]3038[Unsupported tool content removed]
3021```3039```
3022 3040
3023이러한 콘텐츠는 Anthropic API가 아닌 다른 무언가가 API 형식으로 응답했을 때 세션 파일에 들어갑니다. 일반적으로 [`ANTHROPIC_BASE_URL`](https://code.claude.com/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 오류로 실패했습니다.3041이러한 콘텐츠는 Anthropic API가 아닌 다른 무언가가 API 형식으로 응답했을 때 세션 파일에 들어가며, 대표적인 예는 [`ANTHROPIC_BASE_URL`](https://code.claude.com/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 오류로 실패했습니다.
3024 3042
3025**해결 방법:**3043**해결 방법:**
3026 3044
3027* 자리 표시 줄이 보이는 경우에는 조치가 필요하지 않습니다. 세션은 제거된 콘텐츠 없이 계속됩니다.3045* 자리 표시자 줄이 표시되는 경우에는 조치가 필요하지 않습니다. 세션은 제거된 콘텐츠 없이 계속됩니다.
3028* 대신 재개된 세션의 모든 턴이 400 오류로 실패한다면 `claude update`를 실행하고 세션을 다시 재개하십시오. v2.1.246 이전 버전은 해당 콘텐츠를 제거하지 않습니다.3046* 대신 재개된 세션의 모든 턴이 400 오류로 실패하면 `claude update`를 실행하고 세션을 다시 재개하세요. v2.1.246 이전 버전은 콘텐츠를 제거하지 않습니다.
3029 3047
3030### role 'system' must precede an 'assistant' message3048### role 'system' must precede an 'assistant' message
3031 3049
3032대화에서 허용되지 않는 위치에 시스템 메시지가 있기 때문에 API가 400으로 요청을 거부했습니다.3050시스템 메시지가 대화에서 API가 허용하지 않는 위치에 있어 API가 400으로 요청을 거부했습니다:
3033 3051
3034```text theme={null}3052```text theme={null}
3035API Error: 400 messages.6: role 'system' must precede an 'assistant' message or end the array; ...3053API Error: 400 messages.6: role 'system' must precede an 'assistant' message or end the array; ...
3036```3054```
3037 3055
3038Claude Code는 리마인더와 첨부 파일 텍스트 중 일부를 대화 내의 시스템 메시지로 보냅니다. API가 그 위치를 거부하면, Claude Code는 해당 텍스트를 일반 사용자 메시지로 보내는 방식으로 요청을 한 번 재시도합니다. `use the top-level 'system' parameter for the initial system prompt`처럼 API의 유사한 위치 관련 문구에도 같은 복구가 적용됩니다.3056Claude Code는 일부 리마인더 및 첨부 텍스트를 대화 내의 시스템 메시지로 보냅니다. API가 그 위치를 거부하면 Claude Code는 해당 텍스트를 일반 사용자 메시지로 보내 요청을 한 번 재시도합니다. `use the top-level 'system' parameter for the initial system prompt`와 같이 위치에 관한 API의 유사한 문구도 같은 방식으로 복구됩니다.
3039 3057
3040오류가 나타난다면 거부된 시스템 메시지는 Claude Code가 제거할 수 있는 것이 아닙니다. 이는 대개 Claude Code와 API 사이의 프록시나 [LLM 게이트웨이](https://code.claude.com/docs/ko/llm-gateway)가 자체 시스템 메시지를 추가했다는 의미입니다.3058오류가 표시된다면 거부된 시스템 메시지는 Claude Code가 제거할 수 있는 메시지가 아닙니다. 이는 대개 Claude Code와 API 사이의 프록시나 [LLM 게이트웨이](https://code.claude.com/docs/ko/llm-gateway)가 자체 시스템 메시지를 추가했음을 의미합니다.
3041 3059
3042**해결 방법:**3060**해결 방법:**
3043 3061
3044* [`ANTHROPIC_BASE_URL`](https://code.claude.com/docs/ko/env-vars)로 구성된 프록시나 게이트웨이 뒤에서 매 턴마다 오류가 반복된다면, 프록시 없이 연결하여 원인을 확인하고 운영자에게 오류를 보고하십시오3062* [`ANTHROPIC_BASE_URL`](https://code.claude.com/docs/ko/env-vars)로 구성된 프록시나 게이트웨이 뒤에서 매 턴마다 오류가 반복되면, 프록시 없이 연결하여 원인을 확인하고 해당 프록시의 운영자에게 오류를 보고하세요
3045* `/clear`를 실행하여 새 대화를 시작하십시오. 그곳에서도 오류가 다시 발생한다면 원인은 저장된 대화가 아니라 요청 경로에 있습니다.3063* `/clear`를 실행하여 새 대화를 시작하세요. 새 대화에서도 오류가 다시 발생하면 원인은 저장된 대화가 아니라 요청 경로에 있습니다.
3046 3064
3047v2.1.280 이전에는 Claude Code가 이 문구를 인식하지 못했기 때문에, 거부된 시스템 메시지가 Claude Code 자체가 보낸 것인 경우에도 오류가 나타났고 대화의 이후 모든 턴이 같은 방식으로 실패했습니다.3065v2.1.280 이전에는 Claude Code가 이 문구를 인식하지 못했기 때문에, 거부된 시스템 메시지가 Claude Code 자체가 보낸 것인 경우에도 오류가 나타났고 대화의 이후 모든 턴이 같은 방식으로 실패했습니다.
3048 3066
3049### Invalid encrypted\_content in search\_result block3067### Invalid encrypted\_content in search\_result block
3050 3068
3051대화 기록에 API가 복호화할 수 없는 호스팅 웹 검색 콘텐츠가 포함되어 있어 API가 400으로 요청을 거부했습니다. 문구에는 읽을 수 없는 필드가 표시됩니다.3069대화 기록에 API가 복호화할 수 없는 호스팅 웹 검색 콘텐츠가 있어 API가 400으로 요청을 거부했습니다. 문구에는 읽을 수 없는 필드가 명시됩니다:
3052 3070
3053```text theme={null}3071```text theme={null}
3054API Error: 400 ... Invalid `encrypted_content` in `search_result` block3072API Error: 400 ... Invalid `encrypted_content` in `search_result` block
3057API Error: 400 ... Invalid `encrypted_stdout` in `encrypted_code_execution_result` block3075API Error: 400 ... Invalid `encrypted_stdout` in `encrypted_code_execution_result` block
3058```3076```
3059 3077
3060API의 호스팅 [웹 검색 도구](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool)의 결과에는 API만 읽을 수 있는 암호화된 필드가 포함됩니다. `encrypted_stdout` 문구는 이러한 결과를 읽은 호스팅 코드 실행 프로그램의 출력을 가리키며, API는 이 출력도 암호화합니다. API는 다른 조직을 위해 생성된 콘텐츠처럼 복호화할 수 없는 콘텐츠를 다시 보내는 요청을 거부합니다.3078API의 호스팅 [웹 검색 도구](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool)의 결과에는 API만 읽을 수 있는 암호화된 필드가 포함됩니다. `encrypted_stdout` 문구는 이러한 결과를 읽은 호스팅 코드 실행 프로그램의 출력을 가리키며, API는 이 출력도 암호화합니다. API는 다른 조직용으로 생성된 콘텐츠처럼 복호화할 수 없는 콘텐츠를 다시 보내는 요청을 거부합니다.
3061 3079
3062Claude Code 자체의 [WebSearch 도구](https://code.claude.com/docs/ko/tools-reference.md#websearch-tool-behavior)는 검색 결과를 일반 텍스트로 기록하므로, 이러한 블록은 대개 호스팅 웹 검색을 자체적으로 실행한 프록시나 [LLM 게이트웨이](https://code.claude.com/docs/ko/llm-gateway)를 통해 대화에 들어옵니다.3080Claude Code 자체의 [WebSearch 도구](https://code.claude.com/docs/ko/tools-reference.md#websearch-tool-behavior)는 검색 결과를 일반 텍스트로 기록하므로, 이러한 블록은 대개 호스팅 웹 검색을 직접 실행한 프록시나 [LLM 게이트웨이](https://code.claude.com/docs/ko/llm-gateway)를 통해 대화에 들어옵니다.
3063 3081
3064세 가지 웹 검색 문구의 경우, Claude Code는 검색 호출, 결과, 인용을 보내는 내용에서 제외하고 요청을 한 번 재시도하므로, 세션은 오류를 표시하지 않고 계속됩니다. `encrypted_stdout` 문구에는 이런 복구가 없으므로 해당 메시지는 여전히 표시됩니다. v2.1.282 이전에는 Claude Code가 거부된 웹 검색 블록도 유지했기 때문에, 이후의 모든 턴과 `/compact`가 같은 방식으로 실패했습니다.3082세 가지 웹 검색 문구의 경우 Claude Code는 검색 호출, 결과, 인용을 보내는 내용에서 제외하고 요청을 한 번 재시도하므로, 세션은 오류를 표시하지 않고 계속됩니다. `encrypted_stdout` 문구에는 이러한 복구가 없으므로 해당 메시지는 여전히 표시됩니다. v2.1.282 이전에는 Claude Code가 거부된 웹 검색 블록도 유지했기 때문에 이후의 모든 턴과 `/compact`가 같은 방식으로 실패했습니다.
3065 3083
3066**해결 방법:**3084**해결 방법:**
3067 3085
3068* v2.1.281 이하 버전을 사용 중이고 모든 턴이 웹 검색 문구 중 하나로 실패한다면 `claude update`를 실행하고 세션을 재개하십시오3086* v2.1.281 이하를 사용 중이고 모든 턴이 웹 검색 문구 중 하나로 실패하면 `claude update`를 실행하고 세션을 재개하세요
3069* 오류가 지속되거나 메시지에 `encrypted_stdout`이 표시된다면, `/rewind`를 실행하여 해당 콘텐츠를 추가한 턴 이전의 체크포인트로 되돌아가거나, `/clear`를 실행하여 해당 콘텐츠가 포함되지 않은 대화를 시작하십시오3087* 오류가 지속되거나 메시지에 `encrypted_stdout`이 명시되어 있으면 `/rewind`를 실행하여 해당 콘텐츠를 추가한 턴 이전의 체크포인트로 돌아가거나, `/clear`를 실행하여 해당 콘텐츠가 포함되지 않은 대화를 시작하세요
3070* 프록시나 게이트웨이 뒤에서 Claude Code를 실행한다면 운영자에게 오류를 보고하십시오3088* 프록시나 게이트웨이 뒤에서 Claude Code를 실행하는 경우 해당 운영자에게 오류를 보고하세요
3071 3089
3072### Usage Policy refusal3090### 사용 정책 거부
3073 3091
3074대화의 콘텐츠가 [사용 정책](https://www.anthropic.com/legal/aup) 검사를 트리거하여 API가 응답을 거부했습니다.3092대화의 콘텐츠가 [사용 정책](https://www.anthropic.com/legal/aup) 검사를 트리거하여 API가 응답을 거부했습니다.
3075 3093
3076메시지에 `` Details: `[reasoning_extraction]` `` 줄이 포함되어 있다면 [Claude의 추론을 요청하는 요청이 세이프가드에 의해 플래그됨](#safeguards-flagged-a-request-for-claudes-reasoning)을 참조하십시오.3094메시지에 `` Details: `[reasoning_extraction]` `` 줄이 포함되어 있다면 [안전 장치가 Claude의 추론을 요구하는 요청을 플래그 처리함](#safeguards-flagged-a-request-for-claudes-reasoning)을 참조하십시오.
3077 3095
3078메시지에는 거부가 잘못되었다고 판단될 경우 지원팀에 전달할 수 있는 Request ID와 Message ID가 포함되어 있습니다.3096메시지에는 Request ID와 Message ID가 포함되어 있으며, 거부가 잘못되었다고 판단되는 경우 지원팀에 문의할 때 이를 인용할 수 있습니다.
3079 3097
3080```text theme={null}3098```text theme={null}
3081API Error: Opus 4.6 can't help with this. Start a new session to continue.3099API Error: Opus 4.6 can't help with this. Start a new session to continue.
3083Send feedback with /feedback or learn more: https://www.anthropic.com/legal/aup3101Send feedback with /feedback or learn more: https://www.anthropic.com/legal/aup
3084```3102```
3085 3103
3086메시지에는 거부한 모델의 이름이 표시되며, 기록된 모델이 없는 경우에는 `Claude`가 표시됩니다.3104메시지에는 거부한 모델의 이름이 표시되며, 기록된 모델이 없으면 `Claude`가 표시됩니다.
3087 3105
3088이 검사는 최신 프롬프트만이 아니라 전체 대화를 평가하므로, 같은 세션에서 새 메시지를 보내면 대개 동일한 거부가 다시 트리거됩니다. 세션을 종료한 후 `--continue` 또는 `--resume`으로 다시 열어도 디스크의 트랜스크립트에 트리거한 콘텐츠가 여전히 포함되어 있으므로 마찬가지입니다. [Amazon Bedrock](https://code.claude.com/docs/ko/amazon-bedrock.md), [Google Cloud의 Agent Platform](https://code.claude.com/docs/ko/google-vertex-ai.md), [Microsoft Foundry](https://code.claude.com/docs/ko/microsoft-foundry.md)에서는 모델의 안전 조치가 사이버 보안 주제로 플래그한 요청도 이 메시지로 표시됩니다. [안전 조치가 사이버 보안 주제를 플래그함](#safety-measures-flagged-a-cybersecurity-topic)을 참조하십시오.3106이 검사는 최신 프롬프트뿐만 아니라 전체 대화를 평가하므로, 같은 세션에서 새 메시지를 보내면 대개 같은 거부가 다시 트리거됩니다. 세션을 종료한 후 `--continue` 또는 `--resume`으로 다시 열어도 마찬가지인데, 디스크의 트랜스크립트에 트리거한 콘텐츠가 여전히 포함되어 있기 때문입니다. [Amazon Bedrock](https://code.claude.com/docs/ko/amazon-bedrock.md), [Google Cloud의 Agent Platform](https://code.claude.com/docs/ko/google-vertex-ai.md), [Microsoft Foundry](https://code.claude.com/docs/ko/microsoft-foundry.md)에서는 모델의 안전 조치가 사이버 보안 주제로 플래그 처리한 요청에도 이 메시지가 표시됩니다. [안전 조치가 사이버 보안 주제를 플래그 처리함](#safety-measures-flagged-a-cybersecurity-topic)을 참조하십시오.
3089 3107
3090v2.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.`로 표시되었습니다.3108v2.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.`로 표시되었습니다.
3091 3109
3092**해결 방법:**3110**해결 방법:**
3093 3111
3094* Esc를 두 번 누르거나 `/rewind`를 실행하여 거부를 트리거한 턴 이전의 체크포인트로 되돌아간 다음, 표현을 바꾸거나 다른 접근 방식을 사용하십시오. [체크포인트](https://code.claude.com/docs/ko/checkpointing.md)를 참조하십시오.3112* Esc를 두 번 누르거나 `/rewind`를 실행하여 거부를 트리거한 턴 이전의 체크포인트로 되돌아간 다음, 표현을 바꾸거나 다른 접근 방식을 사용합니다. [체크포인트](https://code.claude.com/docs/ko/checkpointing.md)를 참조하십시오.
3095* 어떤 턴이 원인인지 파악할 수 없다면 `/clear`를 실행하여 같은 프로젝트에서 새 대화를 시작하십시오. 이전 대화는 디스크에 보존되며 `/resume`에서 계속 사용할 수 있습니다.3113* 어떤 턴이 원인인지 파악할 수 없다면 `/clear`를 실행하여 같은 프로젝트에서 새 대화를 시작합니다. 이전 대화는 디스크에 보존되며 `/resume`에서 계속 사용할 수 있습니다.
3096* 되감기를 사용할 수 없는 [비대화형 모드](https://code.claude.com/docs/ko/headless.md)(`-p`)에서는 `--continue` 없이 새 세션에서 표현을 바꾼 프롬프트로 재시도하십시오. 정책 검사는 모델마다 다르므로 `--model`로 다른 모델로 전환하면 경우에 따라 거부가 해결될 수도 있습니다.3114* 되감기를 사용할 수 없는 [비대화형 모드](https://code.claude.com/docs/ko/headless.md)(`-p`)에서는 `--continue` 없이 새 세션에서 표현을 바꾼 프롬프트로 재시도합니다. 정책 검사는 모델마다 다르므로, 경우에 따라 `--model`로 다른 모델로 전환하는 것도 거부를 해결할 수 있습니다.
3097 3115
3098### Safety measures flagged a cybersecurity topic3116### 안전 조치가 사이버 보안 주제를 플래그 처리함
3099 3117
3100모델의 안전 조치가 대화의 콘텐츠를 사이버 보안 주제로 플래그했습니다. 메시지에는 요청을 플래그한 모델의 이름이 표시됩니다.3118모델의 안전 조치가 대화의 콘텐츠를 사이버 보안 주제로 플래그 처리했습니다. 메시지에는 요청을 플래그 처리한 모델의 이름이 표시됩니다.
3101 3119
3102```text theme={null}3120```text theme={null}
3103API 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. Send feedback with /feedback or learn more: https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude3121API 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. Send feedback with /feedback or learn more: https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude
3104```3122```
3105 3123
3106메시지에 `` Details: `[reasoning_extraction]` `` 줄이 포함되어 있다면 [Claude의 추론을 요청하는 요청이 세이프가드에 의해 플래그됨](#safeguards-flagged-a-request-for-claudes-reasoning)을 참조하십시오.3124메시지에 `` Details: `[reasoning_extraction]` `` 줄이 포함되어 있다면 [안전 장치가 Claude의 추론을 요구하는 요청을 플래그 처리함](#safeguards-flagged-a-request-for-claudes-reasoning)을 참조하십시오.
3107 3125
3108이 메시지는 정당한 사이버 보안 작업에 대한 액세스 권한을 부여하는 [Cyber Verification Program](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)으로 연결됩니다. [자동 모델 폴백](https://code.claude.com/docs/ko/model-config.md#automatic-model-fallback)이 적용되는 모델은 이 링크가 없는 다른 메시지를 출력하며, Opus 5.5와 Sonnet 5.5에서는 이 메시지가 `<model>'s safeguards flagged this session`으로 시작합니다. 해당 섹션에서는 Claude Code가 대신 모델을 전환하는 경우도 다룹니다.3126이 메시지는 합법적인 사이버 보안 작업을 위한 액세스 권한을 부여하는 [Cyber Verification Program](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)으로 연결됩니다. [자동 모델 폴백](https://code.claude.com/docs/ko/model-config.md#automatic-model-fallback)이 있는 모델은 이 링크 없이 다른 메시지를 출력하며, Opus 5.5와 Sonnet 5.5에서는 `<model>'s safeguards flagged this session`으로 시작합니다. 해당 섹션에서는 Claude Code가 대신 모델을 전환하는 경우도 다룹니다.
3109 3127
3110[Amazon Bedrock](https://code.claude.com/docs/ko/amazon-bedrock.md), [Google Cloud의 Agent Platform](https://code.claude.com/docs/ko/google-vertex-ai.md), [Microsoft Foundry](https://code.claude.com/docs/ko/microsoft-foundry.md)에서는 사이버 보안 플래그가 발생하면 대신 [Usage Policy refusal](#usage-policy-refusal) 메시지가 표시됩니다.3128[Amazon Bedrock](https://code.claude.com/docs/ko/amazon-bedrock.md), [Google Cloud의 Agent Platform](https://code.claude.com/docs/ko/google-vertex-ai.md), [Microsoft Foundry](https://code.claude.com/docs/ko/microsoft-foundry.md)에서는 사이버 보안 플래그가 발생하면 대신 [사용 정책 거부](#usage-policy-refusal) 메시지가 표시됩니다.
3111 3129
3112**해결 방법:**3130**해결 방법:**
3113 3131
3114* 작업에 이 콘텐츠가 필요한 경우 [Cyber Verification Program](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)을 통해 액세스를 신청하십시오3132* 작업에 이 콘텐츠가 필요한 경우 [Cyber Verification Program](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)을 통해 액세스를 신청합니다
3115* 요청이 사이버 보안 주제와 관련이 없었다면 `/feedback`을 실행하여 오탐을 보고하십시오3133* 요청이 사이버 보안 주제와 관련이 없었다면 `/feedback`을 실행하여 오탐을 신고합니다
3116* 같은 세션에서 작업을 계속하려면 Esc를 두 번 누르거나 `/rewind`를 실행하여 플래그를 트리거한 턴 이전의 체크포인트로 되돌아간 다음 다른 접근 방식을 사용하십시오. [체크포인트](https://code.claude.com/docs/ko/checkpointing.md)를 참조하십시오.3134* 같은 세션에서 계속 작업하려면 Esc를 두 번 누르거나 `/rewind`를 실행하여 플래그를 트리거한 턴 이전의 체크포인트로 되돌아간 다음, 다른 접근 방식을 사용합니다. [체크포인트](https://code.claude.com/docs/ko/checkpointing.md)를 참조하십시오.
3117 3135
3118표시된 메시지가 대신 다음 중 하나와 같은 문구라면, 이전 Claude Code 버전에서 발생한 동일한 플래그입니다.3136표시되는 메시지가 대신 다음 중 하나와 같은 문구라면, 이전 Claude Code 버전에서 발생한 동일한 플래그입니다.
3119 3137
3120* v2.1.219부터 v2.1.296까지는 메시지의 마지막 문장 앞에 `Apply to the Cyber Verification Program to reduce these interruptions.`가 포함될 수도 있었습니다3138* v2.1.219부터 v2.1.296까지는 메시지의 마지막 문장 앞에 `Apply to the Cyber Verification Program to reduce these interruptions.`가 포함될 수도 있었습니다
3121* v2.1.203부터 v2.1.218까지는 메시지가 `<model> has safety measures that flagged this message for a cybersecurity topic. To learn about the Cyber Verification Program and apply for access, visit our help center:`로 표시되고 그 뒤에 동일한 고객 센터 링크가 이어졌습니다. 대화형 세션에서는 `If you were not engaging in a cybersecurity topic, please send feedback via /feedback.`가 이어서 표시되었습니다.3139* v2.1.203부터 v2.1.218까지는 메시지가 `<model> has safety measures that flagged this message for a cybersecurity topic. To learn about the Cyber Verification Program and apply for access, visit our help center:` 뒤에 동일한 도움말 센터 링크가 이어지는 형태로 표시되었습니다. 대화형 세션에서는 이어서 `If you were not engaging in a cybersecurity topic, please send feedback via /feedback.`가 표시되었습니다
3122* v2.1.203 이전에는 `<model>'s safeguards flagged this message for a cybersecurity topic. If your work requires this access, you can apply for an exemption:`으로 표시되고 그 뒤에 예외 신청 양식 링크가 이어졌습니다3140* v2.1.203 이전에는 `<model>'s safeguards flagged this message for a cybersecurity topic. If your work requires this access, you can apply for an exemption:` 뒤에 예외 신청 양식 링크가 이어지는 형태로 표시되었습니다
3123 3141
3124### Claude의 추론을 요청하는 요청이 세이프가드에 의해 플래그됨3142### 안전 장치가 Claude의 추론을 요구하는 요청을 플래그 처리함
3125 3143
3126세이프가드가 요청을 모델의 내부 추론을 응답에 재현하도록 요구하는 것으로 플래그했기 때문에 API가 요청을 거부했습니다. API는 이 [거부 범주](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#refusal-response)를 `reasoning_extraction`이라고 부르며, 거부 메시지에는 다음 줄이 포함됩니다.3144안전 장치가 해당 요청을 모델에게 내부 추론을 응답에 재현하도록 요구하는 것으로 플래그 처리하여 API가 요청을 거부했습니다. API는 이 [거부 범주](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#refusal-response)를 `reasoning_extraction`으로 명명하며, 거부 메시지에는 다음 줄이 포함됩니다.
3127 3145
3128```text theme={null}3146```text theme={null}
3129Details: `[reasoning_extraction]`3147Details: `[reasoning_extraction]`
3133 3151
3134**해결 방법:**3152**해결 방법:**
3135 3153
3136* Claude에게 사고 또는 추론을 그대로 또는 고정된 형식으로 작성하도록 요청하는 지시를 제거하거나 표현을 바꾸십시오. 예를 들어 `<thinking>` 섹션, 스크래치패드 섹션, JSON 출력의 `reasoning` 필드 등이 있습니다. 이러한 지시는 프롬프트에 있을 수도 있고, CLAUDE.md, 스킬, 서브에이전트 프롬프트, 출력 스타일, MCP 도구 설명처럼 Claude Code가 프롬프트와 함께 로드하는 사용자 지정 항목에 있을 수도 있습니다.3154* Claude에게 사고나 추론을 그대로 또는 고정된 형식으로 작성하도록 요구하는 지시를 제거하거나 표현을 바꿉니다. 예를 들어 `<thinking>` 섹션, 스크래치패드 섹션, JSON 출력의 `reasoning` 필드 등이 있습니다. 이러한 지시는 프롬프트에 있을 수도 있고, CLAUDE.md, 스킬, 서브에이전트 프롬프트, 출력 스타일, MCP 도구 설명처럼 Claude Code가 프롬프트와 함께 로드하는 사용자 지정 항목에 있을 수도 있습니다.
3137* 사용자 지정 항목이 원인인지 확인하려면 터미널에서 [`claude --safe-mode`](https://code.claude.com/docs/ko/cli-reference#cli-flags)를 실행하여 사용자 지정 항목이 비활성화된 세션을 시작한 다음 같은 프롬프트를 보내십시오3155* 사용자 지정 항목이 트리거인지 확인하려면 터미널에서 [`claude --safe-mode`](https://code.claude.com/docs/ko/cli-reference#cli-flags)를 실행하여 사용자 지정 항목이 비활성화된 세션을 시작한 다음, 같은 프롬프트를 보냅니다
3138* 사용자 지정 항목을 변경한 후에는 새 세션을 시작하십시오3156* 사용자 지정 항목을 변경한 후에는 새 세션을 시작합니다
3139* 이미 보낸 프롬프트의 표현을 바꾸려면 [되감기 및 요약](https://code.claude.com/docs/ko/checkpointing.md#rewind-and-summarize)을 참조하십시오3157* 이미 보낸 프롬프트의 표현을 바꾸려면 [되감기 및 요약](https://code.claude.com/docs/ko/checkpointing.md#rewind-and-summarize)을 참조하십시오
3140* Claude에게 답변을 설명해 달라고 요청하는 것은 여전히 가능합니다. 간단한 설명, 결과의 근거, 또는 수행한 작업의 요약을 요청하십시오. Claude의 사고 요약을 보려면 [`showThinkingSummaries`](https://code.claude.com/docs/ko/settings-reference#showthinkingsummaries)를 참조하십시오.3158* Claude에게 답변을 설명해 달라고 요청하는 것은 여전히 가능합니다. 간단한 설명, 결과의 근거, 또는 수행한 작업의 요약을 요청하십시오. Claude의 사고 요약을 읽으려면 [`showThinkingSummaries`](https://code.claude.com/docs/ko/settings-reference#showthinkingsummaries)를 참조하십시오.
3141* 더 많은 예시와 표현을 바꾼 요청이 여전히 거부될 때의 해결 방법은 [추론을 thinking 블록에 유지하기](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#keep-reasoning-in-thinking-blocks)를 참조하십시오3159* 더 많은 예시와 표현을 바꾼 요청이 여전히 거부되는 경우의 해결 방법은 [추론을 thinking 블록에 유지하기](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#keep-reasoning-in-thinking-blocks)를 참조하십시오
3142 3160
3143### Output blocked by content filtering policy3161### Output blocked by content filtering policy
3144 3162
3150 3168
3151**해결 방법:**3169**해결 방법:**
3152 3170
3153* 마지막 메시지의 표현을 바꾸거나 다른 접근 방식을 사용하십시오3171* 마지막 메시지의 표현을 바꾸거나 다른 접근 방식을 사용합니다
3154* 차단을 트리거한 턴 이전의 체크포인트로 되돌아가려면 Esc를 두 번 누르거나 `/rewind`를 실행하십시오. [체크포인트](https://code.claude.com/docs/ko/checkpointing.md)를 참조하십시오3172* 차단을 트리거한 턴 이전의 체크포인트로 되돌아가려면 Esc를 두 번 누르거나 `/rewind`를 실행합니다. [체크포인트](https://code.claude.com/docs/ko/checkpointing.md)를 참조하십시오
3155 3173
3156## 명령줄 오류3174## 명령줄 오류
3157 3175
3499* **`Error: Workspace not trusted. <folder> is your home directory`**: 홈 디렉터리에 대한 신뢰는 저장되지 않으므로, 그곳에서 먼저 `claude`를 실행해도 도움이 되지 않습니다. 대신 프로젝트 디렉터리에서 `claude`를 한 번 실행하여 신뢰 대화 상자를 수락한 후 그곳에서 `claude ultrareview`를 실행하거나, `--trust-workspace`를 추가합니다.3517* **`Error: Workspace not trusted. <folder> is your home directory`**: 홈 디렉터리에 대한 신뢰는 저장되지 않으므로, 그곳에서 먼저 `claude`를 실행해도 도움이 되지 않습니다. 대신 프로젝트 디렉터리에서 `claude`를 한 번 실행하여 신뢰 대화 상자를 수락한 후 그곳에서 `claude ultrareview`를 실행하거나, `--trust-workspace`를 추가합니다.
3500* **`No answer in time.` 다음에 `Error: Workspace not trusted`**: `Trust <folder>? [y/N]` 질문에 5분 동안 응답이 없었습니다. `claude ultrareview`를 다시 실행하고 질문에 답합니다.3518* **`No answer in time.` 다음에 `Error: Workspace not trusted`**: `Trust <folder>? [y/N]` 질문에 5분 동안 응답이 없었습니다. `claude ultrareview`를 다시 실행하고 질문에 답합니다.
3501* **`Ultrareview did not start: <folder> is not trusted`**: 예를 들어 `n`으로 답하거나 Enter를 눌러 `Trust <folder>? [y/N]` 질문을 거절했습니다. 리뷰를 시작하려면 `claude ultrareview`를 다시 실행하고 `y`로 답합니다.3519* **`Ultrareview did not start: <folder> is not trusted`**: 예를 들어 `n`으로 답하거나 Enter를 눌러 `Trust <folder>? [y/N]` 질문을 거절했습니다. 리뷰를 시작하려면 `claude ultrareview`를 다시 실행하고 `y`로 답합니다.
3502* **``Ultrareview did not start: `--trust-workspace` takes no value``**: PR 번호나 `false`처럼 플래그가 아닌 값이 `--trust-workspace` 뒤에 있습니다. 폴더를 신뢰하지 않는다면 플래그를 빼십시오. 이번 실행에 대해 신뢰하려면 PR 번호나 베이스 브랜치를 플래그 앞에 둡니다: `claude ultrareview 1234 --trust-workspace`.3520* **``Ultrareview did not start: `--trust-workspace` takes no value``**: PR 번호나 `false`처럼 플래그가 아닌 것이 `--trust-workspace` 뒤에 옵니다. 폴더를 신뢰하지 않는다면 플래그를 빼세요. 이번 실행에 대해 신뢰하려면 PR 번호나 기본 브랜치를 플래그 앞에 둡니다: `claude ultrareview 1234 --trust-workspace`.
3503 3521
3504v2.1.309 이전에는 `claude ultrareview`가 `--trust-workspace`를 받지 않았습니다.3522v2.1.309 이전에는 `claude ultrareview`가 `--trust-workspace`를 받지 않았습니다.
3505 3523
3522`remote-control` 동사 앞에 전역 `claude` 플래그를 두고 [Remote Control](https://code.claude.com/docs/ko/remote-control.md)을 시작했으며, 그 플래그는 `--settings`, `--setting-sources`, `--permission-mode`, `--disallowed-tools`, `--mcp-config`처럼 Remote Control이 시작하는 세션을 제한하거나 구성하는 플래그입니다. 동사 앞에 둔 플래그는 해당 세션에 전달되지 않습니다. 대신 Claude Code는 플래그 이름을 표시하며 시작을 거부합니다:3540`remote-control` 동사 앞에 전역 `claude` 플래그를 두고 [Remote Control](https://code.claude.com/docs/ko/remote-control.md)을 시작했으며, 그 플래그는 `--settings`, `--setting-sources`, `--permission-mode`, `--disallowed-tools`, `--mcp-config`처럼 Remote Control이 시작하는 세션을 제한하거나 구성하는 플래그입니다. 동사 앞에 둔 플래그는 해당 세션에 전달되지 않습니다. 대신 Claude Code는 플래그 이름을 표시하며 시작을 거부합니다:
3523 3541
3524```text theme={null}3542```text theme={null}
3525Error: `--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`).3543Error: `--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`). Pass settings with `claude remote-control --settings <file>`.
3526```3544```
3527 3545
3528`--verbose`, `--model`, 또는 래퍼가 주입한 `--session-id`나 `--plugin-dir`처럼 무시해도 문제없는 전역 플래그는 Claude Code가 거부하지 않습니다. 이러한 플래그는 무시되고 Remote Control이 시작됩니다.3546`--verbose`, `--model`, 또는 래퍼가 주입한 `--session-id`나 `--plugin-dir`처럼 무시해도 문제없는 전역 플래그는 Claude Code가 거부하지 않습니다. 이러한 플래그는 무시되고 Remote Control이 시작됩니다.
3536 3554
3537v2.1.248 이전에는 전역 플래그가 먼저 오면 `claude remote-control`이 자체 플래그를 받지 않았으며, 명령이 `unknown option` 오류로 실패했습니다.3555v2.1.248 이전에는 전역 플래그가 먼저 오면 `claude remote-control`이 자체 플래그를 받지 않았으며, 명령이 `unknown option` 오류로 실패했습니다.
3538 3556
3557### `--settings` 파일 때문에 Remote Control이 시작되지 않음
3558
3559[`claude remote-control --settings`](https://code.claude.com/docs/ko/remote-control#start-a-remote-control-session)에 전달한 파일에 문제가 있습니다:
3560
3561```text theme={null}
3562Error: Remote Control did not start, because sessions would skip part or all of the --settings file ./rc-settings.json: Invalid or malformed JSON
3563```
3564
3565**해결 방법:**
3566
3567* 메시지에 언급된 문제를 수정한 후 `claude remote-control` 명령을 다시 실행합니다
3568
3569### Remote Control 시작 이후 설정 파일이 변경됨
3570
3571`claude remote-control`을 실행 중인 터미널에 이 메시지가 표시되면, [`--settings`](https://code.claude.com/docs/ko/remote-control#start-a-remote-control-session)에 전달한 파일의 현재 상태로는 세션이 시작되지 않는다는 의미입니다:
3572
3573```text theme={null}
3574Session failed: Error: The settings file /path/to/settings.json has changed since Remote Control started, so this session did not start. Restart `claude remote-control` to use it as it is now.
3575```
3576
3577**해결 방법:**
3578
3579* 파일을 현재 상태로 사용하려면 `claude remote-control`을 중지하고 같은 명령을 다시 실행합니다. 서버가 제공하던 세션을 다시 불러오려면 [서버 중지 후 세션 재개하기](https://code.claude.com/docs/ko/remote-control.md#resume-sessions-after-stopping-the-server)를 참조하세요.
3580* Remote Control이 시작될 때의 설정을 유지하려면 파일 내용을 원래대로 되돌린 다음, `claude remote-control`이 종료된 경우 명령을 다시 실행합니다
3581
3539### `--sandbox` or `--no-sandbox` is not supported by claude remote-control3582### `--sandbox` or `--no-sandbox` is not supported by claude remote-control
3540 3583
3541이 오류는 [Remote Control](https://code.claude.com/docs/ko/remote-control.md) 서버를 시작하는 명령이 `remote-control` 뒤에 `--sandbox` 또는 `--no-sandbox`를 전달하는데, `claude remote-control`은 두 플래그 모두 받지 않는다는 의미입니다. 서버는 시작하지 않고 종료 코드 1로 종료됩니다:3584이 오류는 [Remote Control](https://code.claude.com/docs/ko/remote-control.md) 서버를 시작하는 명령이 `remote-control` 뒤에 `--sandbox` 또는 `--no-sandbox`를 전달하는데, `claude remote-control`은 두 플래그 모두 받지 않는다는 의미입니다. 서버는 시작하지 않고 종료 코드 1로 종료됩니다:
3806 3849
3807다음 관련 메시지는 명령이 실행되기도 전에 표시됩니다:3850다음 관련 메시지는 명령이 실행되기도 전에 표시됩니다:
3808 3851
3809* `Shell command permission check failed for pattern "..."`: 명령의 권한 검사에서 허용되지 않았습니다. [주입된 명령에 대한 권한 검사](https://code.claude.com/docs/ko/skills.md#permission-checks-on-injected-commands)에서 각 권한 모드에서 어떤 결과가 중단을 일으키는지와 `allowed-tools`로 명령을 사전 승인하는 방법을 다룹니다3852* `Shell command permission check failed for pattern "..."`: 명령의 권한 검사가 이를 허용하지 않았습니다. [주입된 명령의 권한 검사](https://code.claude.com/docs/ko/skills.md#permission-checks-on-injected-commands)에서 각 권한 모드에서 어떤 결과가 중단을 일으키는지와 `allowed-tools`로 명령을 사전 승인하는 방법을 다룹니다
3810* ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found``: 스킬의 frontmatter가 bash가 없는 컴퓨터에서 bash를 요구합니다. Git for Windows를 설치하거나 frontmatter를 `shell: powershell`로 변경합니다. [주입된 명령이 실행되는 방식](https://code.claude.com/docs/ko/skills.md#how-injected-commands-run)을 참조하세요3853* ``Skill <name> requires bash (`shell: bash` in frontmatter) but Git Bash was not found``: 스킬의 frontmatter가 bash가 없는 컴퓨터에서 bash를 요구합니다. Git for Windows를 설치하거나 frontmatter를 `shell: powershell`로 변경합니다. [주입된 명령이 실행되는 방식](https://code.claude.com/docs/ko/skills.md#how-injected-commands-run)을 참조하세요
3811 3854
3812**해결 방법:**3855**해결 방법:**
3960 4003
3961* **기본 브랜치를 전달하지 않은 경우**: Claude Code는 저장소의 기본 브랜치와 비교했으며, 위 예시처럼 기본 브랜치를 명시적으로 전달하도록 제안합니다4004* **기본 브랜치를 전달하지 않은 경우**: Claude Code는 저장소의 기본 브랜치와 비교했으며, 위 예시처럼 기본 브랜치를 명시적으로 전달하도록 제안합니다
3962* **클론에 이미 있던 기본 브랜치를 전달한 경우**: 힌트는 ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``입니다4005* **클론에 이미 있던 기본 브랜치를 전달한 경우**: 힌트는 ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``입니다
3963* **클론에 없던 기본 브랜치를 전달한 경우**: Claude Code가 비교하기 전에 origin에서 해당 브랜치를 가져왔습니다. 힌트는 ``<branch> was fetched from origin but shares no history with HEAD. If another branch is your real base, pass it explicitly (`/code-review ultra <branch>`)``입니다. Claude Code가 클론이 얕은 클론인지 판단할 수 없으면 대신 `git fetch --unshallow origin`을 제안합니다. v2.1.221 이전에는 가져온 모든 기본 브랜치에 대해 힌트가 `git fetch --unshallow origin`을 제안했으며, 완전한 클론에서는 이 명령이 `fatal: --unshallow on a complete repository does not make sense`로 실패합니다.4006* **클론에 없던 기본 브랜치를 전달한 경우**: Claude Code는 비교하기 전에 origin에서 해당 브랜치를 가져왔습니다. 힌트는 ``<branch> was fetched from origin but shares no history with HEAD. If another branch is your real base, pass it explicitly (`/code-review ultra <branch>`)``이며, Claude Code가 클론이 얕은(shallow) 클론인지 판단할 수 없으면 대신 `git fetch --unshallow origin`을 제안합니다. v2.1.221 이전에는 가져온 모든 기본 브랜치에 대해 힌트가 `git fetch --unshallow origin`을 제안했으며, 완전한 클론에서는 이 명령이 `fatal: --unshallow on a complete repository does not make sense`와 함께 실패합니다.
3964 4007
3965**해결 방법:**4008**해결 방법:**
3966 4009
4490commands path escapes plugin directory: ./commands/deploy.md — it resolves to /home/user/shared/deploy.md, outside the plugin directory4533commands path escapes plugin directory: ./commands/deploy.md — it resolves to /home/user/shared/deploy.md, outside the plugin directory
4491```4534```
4492 4535
4493마켓플레이스 플러그인 자체 파일 중 하나(예: `hooks/hooks.json`)의 전체 경로를 제공하는 메시지는 Claude Code가 해당 파일을 건너뛰었음을 의미합니다. 이는 Claude Code가 파일이 플러그인 내부에 있는지, 또는 [로컬 마켓플레이스](https://code.claude.com/docs/ko/plugins/loading.md#in-place-and-copied-plugins)의 플러그인의 경우 해당 마켓플레이스 내부에 있는지 확인할 수 없을 때 발생합니다. 메시지는 이러한 각 파일을 다음 구성 요소 이름으로 보고합니다:4536마켓플레이스 플러그인 자체 파일 중 하나(예: `hooks/hooks.json`)의 전체 경로를 표시하는 메시지는 Claude Code가 해당 파일을 건너뛰었음을 의미합니다. Claude Code는 파일이 플러그인 내부에 있는지, 또는 [로컬 마켓플레이스](https://code.claude.com/docs/ko/plugins/loading.md#in-place-and-copied-plugins)의 플러그인인 경우 해당 마켓플레이스 내부에 있는지 확인할 수 없으면 그 파일을 건너뜁니다. 메시지는 이러한 파일을 다음과 같이 표시된 컴포넌트 이름 아래에 보고합니다:
4494 4537
4495* `hooks/hooks.json`: `hooks`4538* `hooks/hooks.json`: `hooks`
4496* `monitors/monitors.json`: `monitors`4539* `monitors/monitors.json`: `monitors`
4497* `settings.json`: `settings`
4498* 플러그인 루트의 `SKILL.md`: `skills`4540* 플러그인 루트의 `SKILL.md`: `skills`
4499 4541
4500예를 들어 이 메시지는 플러그인과 해당 로컬 마켓플레이스 모두의 외부로 확인되는 `hooks/hooks.json`에 대한 것입니다:4542예를 들어 이 메시지는 플러그인과 해당 로컬 마켓플레이스 모두의 외부로 확인되는 `hooks/hooks.json`에 대한 것입니다:
