55| `spend limit reached` / `spend limit unavailable` | [사용 한도](#spend-limit-reached) |55| `spend limit reached` / `spend limit unavailable` | [사용 한도](#spend-limit-reached) |
56| `Not logged in · Please run /login` | [인증](#not-logged-in) |56| `Not logged in · Please run /login` | [인증](#not-logged-in) |
57| `Couldn't save your login` | [인증](#couldnt-save-your-login) |57| `Couldn't save your login` | [인증](#couldnt-save-your-login) |
58| `Sign in again to take your previous account or API key off the config file.` | [인증](#sign-in-again-to-take-your-previous-account-or-api-key-off-the-config-file) |
59| `Your account or API key may still be in the config file. Run claude auth logout.` | [인증](#your-account-or-api-key-may-still-be-in-the-config-file) |
58| `Authentication required · Sign in again to continue` | [인증](#not-logged-in) |60| `Authentication required · Sign in again to continue` | [인증](#not-logged-in) |
59| `Could not resolve authentication method` | [인증](#could-not-resolve-authentication-method) |61| `Could not resolve authentication method` | [인증](#could-not-resolve-authentication-method) |
60| `Invalid API key` | [인증](#invalid-api-key) |62| `Invalid API key` | [인증](#invalid-api-key) |
82| `Couldn't verify your organization's policy for remote control` | [Remote Control 문제 해결](https://code.claude.com/docs/ko/remote-control.md#couldnt-verify-your-organizations-policy-for-remote-control) |84| `Couldn't verify your organization's policy for remote control` | [Remote Control 문제 해결](https://code.claude.com/docs/ko/remote-control.md#couldnt-verify-your-organizations-policy-for-remote-control) |
83| `Remote Control is disabled by your organization's policy` | [Remote Control 문제 해결](https://code.claude.com/docs/ko/remote-control.md#remote-control-is-disabled-by-your-organizations-policy) |85| `Remote Control is disabled by your organization's policy` | [Remote Control 문제 해결](https://code.claude.com/docs/ko/remote-control.md#remote-control-is-disabled-by-your-organizations-policy) |
84| `Remote Control was turned off by your organization's policy` | [Remote Control 문제 해결](https://code.claude.com/docs/ko/remote-control.md#remote-control-was-turned-off-by-your-organizations-policy) |86| `Remote Control was turned off by your organization's policy` | [Remote Control 문제 해결](https://code.claude.com/docs/ko/remote-control.md#remote-control-was-turned-off-by-your-organizations-policy) |
87| `Session failed: working folder not found:` | [Remote Control 문제 해결](https://code.claude.com/docs/ko/remote-control.md#working-folder-not-found) |
88| `The program file this Remote Control started from is gone` | [Remote Control 문제 해결](https://code.claude.com/docs/ko/remote-control.md#program-file-is-gone) |
89| `Session failed: spawn error:` 뒤에 `ENOENT` 메시지가 이어지는 경우 | [Remote Control 문제 해결](https://code.claude.com/docs/ko/remote-control.md#program-file-is-gone) |
85| `OAuth token revoked` / `OAuth token has expired` | [인증](#oauth-token-revoked-or-expired) |90| `OAuth token revoked` / `OAuth token has expired` | [인증](#oauth-token-revoked-or-expired) |
86| `Failed to authenticate: OAuth token revoked` | [인증](#oauth-token-revoked-or-expired) |91| `Failed to authenticate: OAuth token revoked` | [인증](#oauth-token-revoked-or-expired) |
87| `Your account does not have access to Claude. Please login again or contact your administrator.` | [인증](#oauth-token-revoked-or-expired) |92| `Your account does not have access to Claude. Please login again or contact your administrator.` | [인증](#oauth-token-revoked-or-expired) |
165| `Request too large for the API's 32MB request limit` | [요청 오류](#request-too-large) |170| `Request too large for the API's 32MB request limit` | [요청 오류](#request-too-large) |
166| `Image was too large` | [요청 오류](#image-was-too-large) |171| `Image was too large` | [요청 오류](#image-was-too-large) |
167| `API Error: an image in the conversation could not be processed and was removed` | [요청 오류](#image-was-too-large) |172| `API Error: an image in the conversation could not be processed and was removed` | [요청 오류](#image-was-too-large) |
173| `An image in the conversation exceeds the dimension limit for many-image requests` | [요청 오류](#image-was-too-large) |
168| `Unable to resize image` | [요청 오류](#unable-to-resize-image) |174| `Unable to resize image` | [요청 오류](#unable-to-resize-image) |
169| `Request rejected as unprocessable by the model` | [요청 오류](#request-rejected-as-unprocessable-by-the-model) |175| `Request rejected as unprocessable by the model` | [요청 오류](#request-rejected-as-unprocessable-by-the-model) |
170| `PDF too large` / `PDF is password protected` / `pdftoppm is not installed` | [요청 오류](#pdf-errors) |176| `PDF too large` / `PDF is password protected` / `pdftoppm is not installed` | [요청 오류](#pdf-errors) |
229| `Error: --agents takes a JSON object, or a file path only with --print (-p)` | [명령줄 오류](#invalid-agents-configuration) |235| `Error: --agents takes a JSON object, or a file path only with --print (-p)` | [명령줄 오류](#invalid-agents-configuration) |
230| `Error: --agents file not found` | [명령줄 오류](#invalid-agents-configuration) |236| `Error: --agents file not found` | [명령줄 오류](#invalid-agents-configuration) |
231| `Error: Settings file exceeds the 2MiB limit` | [명령줄 오류](#settings-file-exceeds-the-2mib-limit) |237| `Error: Settings file exceeds the 2MiB limit` | [명령줄 오류](#settings-file-exceeds-the-2mib-limit) |
238| `Configuration error in` | [명령줄 오류](#configuration-error-in-claude-json) |
239| `Claude configuration file at <path> was empty and no backup holds anything: starting with defaults.` | [명령줄 오류](#claude-configuration-file-was-empty) |
232| `The current directory no longer exists (it was deleted or moved)` / `Can't read the current directory` | [명령줄 오류](#the-current-directory-no-longer-exists) |240| `The current directory no longer exists (it was deleted or moved)` / `Can't read the current directory` | [명령줄 오류](#the-current-directory-no-longer-exists) |
233| `Temp directory <dir> ... Refusing to use it` / `Claude Code's temporary directory <dir> could not be created` | [명령줄 오류](#temp-directory-refused-or-cannot-be-created) |241| `Temp directory <dir> ... Refusing to use it` / `Claude Code's temporary directory <dir> could not be created` | [명령줄 오류](#temp-directory-refused-or-cannot-be-created) |
234| `ENOSPC: no space left on device, mkdir '<dir>'` | [명령줄 오류](#temp-directory-refused-or-cannot-be-created) |242| `ENOSPC: no space left on device, mkdir '<dir>'` | [명령줄 오류](#temp-directory-refused-or-cannot-be-created) |
334| `cannot contain null bytes (\0)` | [도구 오류](#path-cannot-contain-null-bytes) |342| `cannot contain null bytes (\0)` | [도구 오류](#path-cannot-contain-null-bytes) |
335| `Path contains null bytes` | [도구 오류](#path-cannot-contain-null-bytes) |343| `Path contains null bytes` | [도구 오류](#path-cannot-contain-null-bytes) |
336| `command contains the invisible character U+FEFF (byte order mark) or U+180E (Mongolian vowel separator), and was not run` | [도구 오류](#command-contains-an-invisible-character) |344| `command contains the invisible character U+FEFF (byte order mark) or U+180E (Mongolian vowel separator), and was not run` | [도구 오류](#command-contains-an-invisible-character) |
345| `This call was not run. The command was approved before Claude Code restarted` | [도구 오류](#command-approved-before-a-restart-was-not-run) |
337| `File is too large to read as an image (the limit is 128MB)` | [도구 오류](#file-is-too-large-to-read-as-an-image) |346| `File is too large to read as an image (the limit is 128MB)` | [도구 오류](#file-is-too-large-to-read-as-an-image) |
338| `Cannot read this as an image: <path> is a pipe or a device` | [도구 오류](#file-is-too-large-to-read-as-an-image) |347| `Cannot read this as an image: <path> is a pipe or a device` | [도구 오류](#file-is-too-large-to-read-as-an-image) |
339| `subagent_type is required: the general-purpose agent is not available in this session` | [도구 오류](#subagent-type-is-required) |348| `subagent_type is required: the general-purpose agent is not available in this session` | [도구 오류](#subagent-type-is-required) |
420| `Not loaded: rename <path>, then restart — its name uses "<name>", a name reserved for the skills synced from your claude.ai account` | [구성 경고](#a-skill-command-or-workflow-wasnt-loaded-because-its-name-is-reserved) |429| `Not loaded: rename <path>, then restart — its name uses "<name>", a name reserved for the skills synced from your claude.ai account` | [구성 경고](#a-skill-command-or-workflow-wasnt-loaded-because-its-name-is-reserved) |
421| `N skill or command names refused: run with --debug to see which ([names]), rename, then restart` | [구성 경고](#skill-or-command-name-refused) |430| `N skill or command names refused: run with --debug to see which ([names]), rename, then restart` | [구성 경고](#skill-or-command-name-refused) |
422| `Ignoring N permissions.allow entries from ... this workspace has not been trusted` | [구성 경고](#workspace-has-not-been-trusted) |431| `Ignoring N permissions.allow entries from ... this workspace has not been trusted` | [구성 경고](#workspace-has-not-been-trusted) |
432| `Make this change again later: <path> could not be updated, so it applies to this session only` | [구성 경고](#make-this-change-again-later) |
423| `is a network path, which cannot be added as a working directory` | [구성 경고](#working-directory-is-a-network-path) |433| `is a network path, which cannot be added as a working directory` | [구성 경고](#working-directory-is-a-network-path) |
424| `Remote managed settings failed to load (<cause>)` | [구성 경고](#remote-managed-settings-failed-to-load) |434| `Remote managed settings failed to load (<cause>)` | [구성 경고](#remote-managed-settings-failed-to-load) |
435| `Your organization requires remote managed settings to load, but they could not be loaded` | [fail-closed 시작 강제](https://code.claude.com/docs/ko/server-managed-settings.md#enforce-fail-closed-startup) |
436| `Remote managed settings are still loading` | [구성 경고](#remote-managed-settings-failed-to-load) |
437| `Remote managed settings did not load` | [구성 경고](#remote-managed-settings-failed-to-load) |
438| `Claude Code couldn't load your organization's settings` / `Claude Code couldn't reach Anthropic to load your organization's settings` / `requires them before a session can start` | [구성 경고](#couldnt-load-your-organizations-settings) |
439| `Claude Code can't start this session yet` | [구성 경고](#couldnt-load-your-organizations-settings) |
440| `Your Claude session has expired. Sign in again to continue (claude auth login).` | [구성 경고](#couldnt-load-your-organizations-settings) |
425| `Managed settings were not approved; exiting without applying them.` | [구성 경고](#managed-settings-were-not-approved) |441| `Managed settings were not approved; exiting without applying them.` | [구성 경고](#managed-settings-were-not-approved) |
426| `Your organization's managed settings need your approval, which couldn't be asked for here.` | [구성 경고](#managed-settings-need-your-approval) |442| `Your organization's managed settings need your approval, which couldn't be asked for here.` | [구성 경고](#managed-settings-need-your-approval) |
427| `Claude Code can't start: your organization's managed settings block the default model` / `Claude Code can't start: your organization allows only the models listed in "availableModels"` | [구성 경고](#managed-settings-block-the-default-model) |443| `Claude Code can't start: your organization's managed settings block the default model` / `Claude Code can't start: your organization allows only the models listed in "availableModels"` | [구성 경고](#managed-settings-block-the-default-model) |
454| `is ignored — managed settings set allowManagedReadPathsOnly` / `is ignored — managed settings set allowManagedDomainsOnly` | [구성 경고](#sandbox-allow-entries-are-ignored-under-a-managed-lock) |470| `is ignored — managed settings set allowManagedReadPathsOnly` / `is ignored — managed settings set allowManagedDomainsOnly` | [구성 경고](#sandbox-allow-entries-are-ignored-under-a-managed-lock) |
455| `Sandbox mask files left behind at write-deny paths` | [구성 경고](#stale-sandbox-mask-files-left-by-a-killed-session) |471| `Sandbox mask files left behind at write-deny paths` | [구성 경고](#stale-sandbox-mask-files-left-by-a-killed-session) |
456| `Stale sandbox mask files left by a killed session` | [구성 경고](#stale-sandbox-mask-files-left-by-a-killed-session) |472| `Stale sandbox mask files left by a killed session` | [구성 경고](#stale-sandbox-mask-files-left-by-a-killed-session) |
473| `Ubuntu's AppArmor restriction on user namespaces stops bubblewrap here` | [샌드박싱 문제 해결](https://code.claude.com/docs/ko/sandboxing.md#apparmor-restriction-stops-bubblewrap) |
474| `bwrap: setting up uid map: Permission denied` / `bwrap: loopback: Failed RTM_NEWADDR: Operation not permitted` | [샌드박싱 문제 해결](https://code.claude.com/docs/ko/sandboxing.md#bwrap-uid-map-permission-denied) |
457| 응답 품질이 평소보다 낮아 보임 | [응답 품질](#responses-seem-lower-quality-than-usual) |475| 응답 품질이 평소보다 낮아 보임 | [응답 품질](#responses-seem-lower-quality-than-usual) |
458 476
459## 자동 재시도477## 자동 재시도
1031* `/login`을 실행하여 Claude 구독 또는 Console 계정으로 인증합니다1049* `/login`을 실행하여 Claude 구독 또는 Console 계정으로 인증합니다
1032* 환경 변수로 인증될 것으로 예상했다면, `claude`를 실행한 셸에서 `ANTHROPIC_API_KEY`가 설정되고 export되었는지 확인합니다1050* 환경 변수로 인증될 것으로 예상했다면, `claude`를 실행한 셸에서 `ANTHROPIC_API_KEY`가 설정되고 export되었는지 확인합니다
1033* 대화형 로그인이 불가능한 CI 또는 자동화 환경에서는 시작 시 키를 가져오는 [`apiKeyHelper`](https://code.claude.com/docs/ko/settings-reference#apikeyhelper) 스크립트를 구성합니다1051* 대화형 로그인이 불가능한 CI 또는 자동화 환경에서는 시작 시 키를 가져오는 [`apiKeyHelper`](https://code.claude.com/docs/ko/settings-reference#apikeyhelper) 스크립트를 구성합니다
1052* 누군가 동일한 claude.ai 계정과 조직으로 다시 로그인할 때 `claude -p` 작업이 이 메시지와 함께 종료된다면, 해당 로그인이 실행되는 곳의 Claude Code를 업데이트합니다. v2.1.318 이전에는 Claude Code가 해당 로그인 중에 새 로그인을 저장하기 전에 저장된 로그인을 제거했습니다.
1034* 여러 자격 증명이 있을 때 Claude Code가 어떤 자격 증명을 사용하는지 알아보려면 [인증 우선순위](https://code.claude.com/docs/ko/authentication.md#authentication-precedence)를 참조하십시오1053* 여러 자격 증명이 있을 때 Claude Code가 어떤 자격 증명을 사용하는지 알아보려면 [인증 우선순위](https://code.claude.com/docs/ko/authentication.md#authentication-precedence)를 참조하십시오
1035 1054
1036로그인을 반복적으로 요청받는 경우, 시스템 시계 확인 방법과 macOS 자격 증명 저장소 복구 단계는 [로그인되지 않음 또는 토큰 만료](https://code.claude.com/docs/ko/troubleshoot-install.md#not-logged-in-or-token-expired)를 참조하십시오.1055로그인을 반복적으로 요청받는 경우, 시스템 시계 확인 방법과 macOS 자격 증명 저장소 복구 단계는 [로그인되지 않음 또는 토큰 만료](https://code.claude.com/docs/ko/troubleshoot-install.md#not-logged-in-or-token-expired)를 참조하십시오.
1441* 다른 플랫폼에서는 `/login`을 다시 실행합니다1460* 다른 플랫폼에서는 `/login`을 다시 실행합니다
1442* 로그인이 여전히 저장되지 않으면, 키체인 잠금 해제 명령과 기타 자격 증명 저장소 복구 단계는 [로그인되지 않음 또는 토큰 만료](https://code.claude.com/docs/ko/troubleshoot-install.md#not-logged-in-or-token-expired)를 참조하십시오1461* 로그인이 여전히 저장되지 않으면, 키체인 잠금 해제 명령과 기타 자격 증명 저장소 복구 단계는 [로그인되지 않음 또는 토큰 만료](https://code.claude.com/docs/ko/troubleshoot-install.md#not-logged-in-or-token-expired)를 참조하십시오
1443 1462
1463### Sign in again to take your previous account or API key off the config file
1464
1465로그인 후 나타나는 이 경고는 이전에 로그인했던 계정이 [`~/.claude.json`](https://code.claude.com/docs/ko/claude-directory#ce-claude-json)에 여전히 저장되어 있을 수 있음을 의미합니다.
1466
1467```text theme={null}
1468Sign in again to take your previous account or API key off the config file.
1469```
1470
1471Linux 또는 Windows에서 Console 로그인이 API 키를 생성한 경우, 해당 API 키도 `~/.claude.json`에 남아 있을 수 있습니다.
1472
1473**해결 방법:**
1474
1475* 셸에서 `claude auth login`을 실행하여 다시 로그인합니다. 그러면 Claude Code가 교체된 계정이나 API 키를 파일에서 제거하는 저장을 다시 시도합니다.
1476
1477### Your account or API key may still be in the config file
1478
1479`/logout` 또는 `claude auth logout`을 실행했고 Claude Code가 이 프로세스를 로그아웃했지만, [`~/.claude.json`](https://code.claude.com/docs/ko/claude-directory#ce-claude-json)에 더 이상 계정이 없는지 확인할 수 없었습니다. 저장이 반영되지 않았거나, 확인을 위해 파일을 다시 읽을 수 없었습니다.
1480
1481```text theme={null}
1482Your account or API key may still be in the config file. Run claude auth logout.
1483```
1484
1485Linux 또는 Windows에서 Console 로그인이 API 키를 생성한 경우, 해당 API 키도 `~/.claude.json`에 남아 있을 수 있습니다.
1486
1487**해결 방법:**
1488
1489* 셸에서 `claude auth logout`을 실행하여 저장을 다시 시도합니다. 저장이 완료되면 명령이 `Successfully logged out from your Anthropic account.`를 출력합니다.
1490
1444### Couldn't start the local listener that receives the browser sign-in1491### Couldn't start the local listener that receives the browser sign-in
1445 1492
1446`/login`, `claude auth login` 또는 `claude setup-token`에서 표시되는 다음 메시지들은 모두 Claude Code가 브라우저가 로그인 결과를 반환하는 `127.0.0.1`의 포트를 열 수 없었다는 의미입니다.1493`/login`, `claude auth login` 또는 `claude setup-token`에서 표시되는 다음 메시지들은 모두 Claude Code가 브라우저가 로그인 결과를 반환하는 `127.0.0.1`의 포트를 열 수 없었다는 의미입니다.
2288 2335
2289## 요청 오류2336## 요청 오류
2290 2337
2291이 오류들은 요청의 내용과 관련이 있습니다. 대부분은 API가 요청을 거부한 후 반환되며, 일부는 요청이 전송되기 전에 Claude Code가 로컬에서 생성합니다.2338이 오류들은 요청의 내용과 관련이 있습니다. 대부분은 API가 요청을 거부한 후 API에서 반환되며, 일부는 요청이 전송되기 전에 Claude Code가 로컬에서 생성합니다.
2292 2339
2293### Prompt is too long2340### Prompt is too long
2294 2341
2295대화와 첨부 파일의 합이 모델의 컨텍스트 윈도우를 초과했습니다.2342대화와 첨부 파일을 합친 크기가 모델의 컨텍스트 윈도우를 초과했습니다.
2296 2343
2297```text theme={null}2344```text theme={null}
2298Prompt is too long2345Prompt is too long
2304Context limit reached · /compact or /clear to continue2351Context limit reached · /compact or /clear to continue
2305```2352```
2306 2353
2307[`DISABLE_COMPACT`](https://code.claude.com/docs/ko/env-vars)가 설정된 경우 이 줄에는 `/clear`만 표시됩니다. 아래의 압축 실패 형태와 같은 더 긴 형태의 오류는 `Prompt is too long ·` 문구를 유지합니다. `-p` 출력과 트랜스크립트에서는 텍스트가 `Prompt is too long`으로 유지됩니다.2354[`DISABLE_COMPACT`](https://code.claude.com/docs/ko/env-vars)가 설정되어 있으면 이 줄에는 `/clear`만 표시됩니다. 아래의 압축 실패 형식과 같이 더 긴 형식의 오류는 `Prompt is too long ·` 문구를 유지합니다. `-p` 출력과 트랜스크립트에서는 텍스트가 `Prompt is too long`으로 유지됩니다.
2308 2355
2309[사용자 설정](https://code.claude.com/docs/ko/settings-reference.md#autocompactenabled)에서 자동 압축을 끈 경우, 이 줄에 해당 내용도 표시됩니다.2356[사용자 설정](https://code.claude.com/docs/ko/settings-reference.md#autocompactenabled)에서 자동 압축을 끈 경우, 이 줄에 그 사실도 함께 표시됩니다.
2310 2357
2311```text theme={null}2358```text theme={null}
2312Context limit reached · /compact or /clear to continue · auto-compact is off · /config to turn it on2359Context limit reached · /compact or /clear to continue · auto-compact is off · /config to turn it on
2313```2360```
2314 2361
2315`/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 이전에는 이 줄에 자동 압축 힌트가 없었습니다.2362`/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 이전에는 이 줄에 자동 압축 힌트가 포함되지 않았습니다.
2316 2363
2317Amazon Bedrock은 이 상황을 `Input is too long for requested model.`로 보고하며, Claude Code는 이를 동일하게 처리합니다. v2.1.217 이전에는 Claude Code가 Bedrock 문구를 인식하지 못했기 때문에 자동 압축이 트리거되지 않았고 `/compact`도 같은 오류로 실패했습니다.2364Amazon Bedrock은 이 상태를 `Input is too long for requested model.`로 보고하며, Claude Code는 이를 동일한 방식으로 처리합니다. v2.1.217 이전에는 Claude Code가 Bedrock의 문구를 인식하지 못했기 때문에 자동 압축이 이 오류에서 트리거되지 않았고 `/compact`도 같은 오류로 실패했습니다.
2318 2365
2319[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가 이 토큰을 인식하지 못했기 때문에 자동 압축이 트리거되지 않았습니다.2366[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가 이 토큰을 인식하지 못했기 때문에 자동 압축이 트리거되지 않았습니다.
2320 2367
2321이번 턴에서 자동 압축이 실행되었지만 사용할 수 없는 모델이나 인증 실패와 같은 근본 오류로 실패한 경우, 메시지는 구분 기호 뒤에 해당 오류를 표시합니다.2368이번 턴에 자동 압축이 실행되었으나 사용할 수 없는 모델이나 인증 실패 같은 근본 오류로 실패한 경우, 메시지는 구분 기호 뒤에 해당 오류를 표시합니다.
2322 2369
2323```text theme={null}2370```text theme={null}
2324Prompt is too long · automatic compaction failed: <the underlying error>2371Prompt is too long · automatic compaction failed: <the underlying error>
2326 2373
2327표시된 오류를 먼저 해결하십시오. 해결하기 전까지 `/compact`도 같은 오류로 실패합니다. v2.1.229 이전에는 자동 압축이 실패하면 원인 없이 `Prompt is too long`만 표시되었습니다.2374표시된 오류를 먼저 해결하십시오. 해결하기 전까지 `/compact`도 같은 오류로 실패합니다. v2.1.229 이전에는 자동 압축이 실패하면 원인 없이 `Prompt is too long`만 표시되었습니다.
2328 2375
2329이 오류에 대해 자동 압축이 실행되면 일반적으로 가장 오래된 대화 교환을 요약하고 최신 교환은 유지합니다. 최후의 수단으로 Claude Code는 다르게 요약합니다.2376이 오류에서 자동 압축이 실행되면 일반적으로 가장 오래된 대화 교환을 요약하고 최신 교환은 유지합니다. 최후의 수단으로 Claude Code는 다르게 요약합니다.
2330 2377
2331* 어떤 교환 전체도 요약할 수 없는 경우, Claude Code는 최신 프롬프트를 그대로 유지하고 그 이전의 모든 내용을 요약합니다.2378* 온전한 교환을 하나도 요약할 수 없는 경우, Claude Code는 최신 프롬프트를 그대로 유지하고 그 이전의 모든 내용을 요약합니다.
2332* 이 경우 대화가 사용자의 프롬프트로 끝나지 않으면, Claude Code는 대신 대화 전체를 요약합니다.2379* 이 경우 대화가 사용자의 프롬프트로 끝나지 않으면, Claude Code는 대신 전체 대화를 요약합니다.
2333 2380
2334이어서 전달할 내용에 모델 응답이 없고 사용자 자신의 텍스트가 약 1,000 토큰 미만인 경우(예: 너무 큰 붙여넣기 후 보낸 짧은 재시도), Claude Code는 이 복구를 건너뜁니다. 새로 시작하려면 `/clear`를 실행하십시오. v2.1.269 이전에는 교환 전체를 요약할 수 없을 때마다 압축이 실패했기 때문에, 그런 상태의 세션은 매 턴마다 이 오류가 다시 발생했습니다.2381이어서 유지할 내용에 모델 응답이 없고 사용자가 작성한 텍스트가 약 1,000토큰 미만인 경우(예: 너무 큰 붙여넣기 이후 보낸 짧은 재시도), Claude Code는 이 복구를 건너뜁니다. 새로 시작하려면 `/clear`를 실행하십시오. v2.1.269 이전에는 온전한 교환을 요약할 수 없을 때마다 압축이 실패했기 때문에, 그런 상태의 세션은 매 턴마다 이 오류가 다시 발생했습니다.
2335 2382
2336단일 교환으로 이루어진 대화에는 요약할 이전 턴이 없습니다. 이런 대화에서 자동 압축이 실행될 상황이 되면, Claude Code는 시도를 건너뛰고 대신 요청을 채우는 내용이 무엇인지 설명합니다. API가 오류에 토큰 수를 보고하지 않는 경우 메시지는 다음과 같습니다.2383교환이 하나뿐인 대화에는 요약할 이전 턴이 없습니다. 이런 대화에서 자동 압축이 실행될 상황이 되면, Claude Code는 시도를 건너뛰고 대신 무엇이 요청을 채우고 있는지 설명합니다. API가 오류에 토큰 수를 보고하지 않는 경우 메시지는 다음과 같습니다.
2337 2384
2338```text theme={null}2385```text theme={null}
2339Prompt 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.2386Prompt 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.
2340```2387```
2341 2388
2342API가 오류에 토큰 수를 보고하는 경우, Claude Code는 이를 대화 크기에 대한 자체 추정치와 비교하여 요청의 대부분이 대화 자체의 내용인지, 아니면 Claude Code가 함께 보내는 시스템 프롬프트, 도구 정의, 첨부 내용인지 판단합니다. 대화 자체의 내용이 요청의 대부분인 경우 메시지는 다음과 같습니다.2389API가 오류에 토큰 수를 보고하는 경우, Claude Code는 이를 대화 크기에 대한 자체 추정치와 비교하여 요청의 대부분이 대화 자체의 내용인지, 아니면 Claude Code가 함께 보내는 시스템 프롬프트, 도구 정의, 첨부 파일 내용인지 판단합니다. 대화 자체의 내용이 요청의 대부분을 차지하는 경우 메시지는 다음과 같습니다.
2343 2390
2344```text theme={null}2391```text theme={null}
2345Prompt 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).2392Prompt 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).
2355 2402
2356**해결 방법:**2403**해결 방법:**
2357 2404
2358* `/compact`를 실행하여 이전 턴을 요약하고 공간을 확보하거나, `/clear`를 실행하여 새로 시작합니다. `/compact`가 `Not enough messages to compact.`로 응답하면 대화가 요약할 이전 내용이 없는 단일 교환이라는 뜻이므로, 공간은 그 하나의 프롬프트와 Claude Code가 모든 요청에 함께 보내는 내용이 차지하고 있습니다. `/clear`를 실행하고 붙여넣은 텍스트를 줄이거나 더 작은 첨부 파일로 다시 보내거나, 아래 단계에 따라 도구 정의와 메모리 파일을 줄이십시오2405* `/compact`를 실행하여 이전 턴을 요약하고 공간을 확보하거나, `/clear`를 실행하여 새로 시작하십시오. `/compact`가 `Not enough messages to compact.`로 응답하면 대화가 요약할 이전 내용이 없는 단일 교환이라는 뜻이므로, 공간은 그 하나의 프롬프트와 Claude Code가 모든 요청에 함께 보내는 내용이 차지하고 있습니다. `/clear`를 실행한 후 붙여넣는 텍스트를 줄이거나 더 작은 첨부 파일로 다시 보내거나, 아래 단계에 따라 도구 정의와 메모리 파일을 줄이십시오
2359* `/context`를 실행하여 시스템 프롬프트, 도구, 메모리 파일, 메시지 등 윈도우를 차지하는 항목의 세부 내역을 확인합니다2406* `/context`를 실행하면 시스템 프롬프트, 도구, 메모리 파일, 메시지 등 무엇이 윈도우를 차지하고 있는지 세부 내역을 확인할 수 있습니다
2360* 사용하지 않는 MCP 서버를 `/mcp disable <name>`으로 비활성화하여 해당 도구 정의를 컨텍스트에서 제거합니다2407* 사용하지 않는 MCP 서버를 `/mcp disable <name>`으로 비활성화하여 해당 도구 정의를 컨텍스트에서 제거하십시오
2361* 큰 `CLAUDE.md` 메모리 파일을 정리하거나, 관련 있을 때만 로드되는 [경로 범위 규칙](https://code.claude.com/docs/ko/memory.md#path-specific-rules)으로 지침을 옮깁니다2408* 큰 `CLAUDE.md` 메모리 파일을 줄이거나, 관련이 있을 때만 로드되는 [경로 범위 규칙](https://code.claude.com/docs/ko/memory.md#path-specific-rules)으로 지침을 옮기십시오
2362* 자동 압축은 기본적으로 켜져 있으며 일반적으로 이 오류를 방지합니다. `/config` 또는 [`DISABLE_AUTO_COMPACT`](https://code.claude.com/docs/ko/env-vars)로 끈 경우 다시 켜십시오. 계속 꺼 두려면 윈도우가 가득 차기 전에 직접 `/compact`를 실행하십시오.2409* 자동 압축은 기본적으로 켜져 있으며 일반적으로 이 오류를 방지합니다. `/config`에서 또는 [`DISABLE_AUTO_COMPACT`](https://code.claude.com/docs/ko/env-vars)로 자동 압축을 끈 경우 다시 켜십시오. 계속 끈 상태로 두려면 윈도우가 가득 차기 전에 직접 `/compact`를 실행하십시오.
2363* 더 큰 컨텍스트를 지원하는 모델에서 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)하십시오.2410* 더 큰 컨텍스트를 지원하는 모델에서 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)하십시오.
2364 * 사용자 지정 [`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 윈도우 근처에서 요청을 보내는 대신 이 메시지로 턴을 종료했습니다.2411 * 사용자 지정 [`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 윈도우 근처에서 요청을 보내는 대신 해당 메시지와 함께 턴을 종료했습니다.
2365* Claude가 대화를 압축하는 도중에 중지한 직후 오류가 나타났다면, 대화는 변경되지 않았으며 여전히 압축이 필요할 만큼 큽니다. `/compact`를 실행하고 메시지를 다시 보내세요. 오류가 재발하지 않도록 하려면 Claude Code를 v2.1.304 이상으로 [업데이트](https://code.claude.com/docs/ko/setup.md#update-claude-code)하세요. v2.1.304 이전에는 그 시점에 중지하면 턴이 이 오류로 끝날 수 있었습니다.2412* Claude가 대화를 압축하는 도중에 중지한 직후 오류가 나타났다면, 대화는 변경되지 않았으며 여전히 압축이 필요할 만큼 큽니다. `/compact`를 실행하고 메시지를 다시 보내십시오. 오류가 재발하지 않도록 하려면 [Claude Code를 업데이트](https://code.claude.com/docs/ko/setup.md#update-claude-code)하여 v2.1.304 이상으로 만드십시오. v2.1.304 이전에는 그 시점에 중지하면 이 오류와 함께 턴이 종료될 수 있었습니다.
2366* 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 이상으로 올리십시오.2413* 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 이상으로 만드십시오.
2367 2414
2368컨텍스트가 채워지는 방식을 대화형으로 확인하려면 [컨텍스트 윈도우 살펴보기](https://code.claude.com/docs/ko/context-window.md)를 참조하십시오.2415컨텍스트가 채워지는 방식을 대화형으로 보려면 [컨텍스트 윈도우 살펴보기](https://code.claude.com/docs/ko/context-window.md)를 참조하십시오.
2369 2416
2370### Context exceeds the token limit2417### 컨텍스트가 토큰 한도를 초과함
2371 2418
2372대화가 모델의 컨텍스트 윈도우를 넘어서 커진 경우 `/context`는 출력 상단에 이 경고를 표시합니다. 공간을 확보할 때까지 요청은 [`Prompt is too long`](#prompt-is-too-long)으로 실패합니다. 대화형 세션은 이 오류를 `Context limit reached` 줄로 표시합니다.2419대화가 모델의 컨텍스트 윈도우를 넘어설 만큼 커지면 `/context`는 출력 상단에 이 경고를 표시합니다. 공간을 확보할 때까지 요청은 [`Prompt is too long`](#prompt-is-too-long)으로 실패합니다. 대화형 세션에서는 이 오류가 `Context limit reached` 줄로 표시됩니다.
2373 2420
2374```text theme={null}2421```text theme={null}
2375Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.2422Context exceeds the 200k-token limit by 94k tokens — run /compact or /clear to continue.
2376```2423```
2377 2424
2378초과한 한도가 1M 컨텍스트 모델의 200K 경계와 같은 압축 윈도우인 경우 경고 문구가 달라집니다. 압축 윈도우는 모델의 컨텍스트 윈도우보다 작을 수 있으므로, 이를 넘은 요청도 여전히 성공할 수 있습니다.2425초과한 한도가 1M 컨텍스트 모델의 200K 경계처럼 압축 윈도우인 경우 경고 문구가 다릅니다. 압축 윈도우는 모델의 컨텍스트 윈도우보다 작을 수 있으므로, 이를 넘어선 요청도 여전히 성공할 수 있습니다.
2379 2426
2380```text theme={null}2427```text theme={null}
2381Context is 94k tokens past the 200k-token compaction window — run /compact to reduce usage.2428Context is 94k tokens past the 200k-token compaction window — run /compact to reduce usage.
2382```2429```
2383 2430
2384[`DISABLE_COMPACT`](https://code.claude.com/docs/ko/env-vars)를 설정한 경우 두 형태 모두 `/compact` 대신 `/clear`를 표시합니다.2431[`DISABLE_COMPACT`](https://code.claude.com/docs/ko/env-vars)를 설정한 경우 두 형식 모두 `/compact` 대신 `/clear`를 표시합니다.
2385 2432
2386**해결 방법:**2433**해결 방법:**
2387 2434
2388* 여러 턴으로 이루어진 대화에서는 `/compact`를 실행하여 이전 턴을 요약하고 공간을 확보합니다. 대신 새로 시작하려면 `/clear`를 실행합니다2435* 여러 턴으로 이루어진 대화에서는 `/compact`를 실행하여 이전 턴을 요약하고 공간을 확보하십시오. 대신 새로 시작하려면 `/clear`를 실행하십시오
2389* 사용량을 줄이는 다른 방법은 [Prompt is too long](#prompt-is-too-long)을 참조하십시오2436* 사용량을 줄이는 더 많은 방법은 [Prompt is too long](#prompt-is-too-long)을 참조하십시오
2390 2437
2391v2.1.216 이전에는 `/context`가 100%를 넘는 사용량을 표시하면서도 그 의미나 복구 방법을 설명하는 경고 줄을 표시하지 않았습니다.2438v2.1.216 이전에는 `/context`가 100%를 넘는 사용량을 표시하면서도 그 의미나 복구 방법을 설명하는 경고 줄을 표시하지 않았습니다.
2392 2439
2398Request 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.2445Request 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.
2399```2446```
2400 2447
2401요청이 Claude API로 직접 전송되었고 API 자체가 이를 거부한 경우, Claude Code는 대화를 측정하고 복구가 가능한지에 따라 메시지 문구를 정합니다. 프록시, 게이트웨이 또는 클라우드 공급자를 거치는 경우에는 일반 메시지가 표시됩니다. 측정된 형태는 다음과 같습니다.2448요청이 Claude API로 직접 전송되었고 API 자체가 이를 거부한 경우, Claude Code는 대화 크기를 측정하고 복구가 가능한지에 따라 메시지 문구를 정합니다. 프록시, 게이트웨이 또는 클라우드 제공업체를 거친 경우에는 일반 메시지가 표시됩니다. 측정된 형식은 다음과 같습니다.
2402 2449
2403* `Request too large (max 32MB; 20.1MB of about 33.4MB is images or documents).`: 이미지나 문서 때문에 요청이 한도를 초과했습니다. Claude Code는 이를 제거한 상태로 재시도합니다.2450* `Request too large (max 32MB; 20.1MB of about 33.4MB is images or documents).`: 이미지나 문서 때문에 요청이 한도를 초과했습니다. Claude Code는 이를 제거한 후 재시도합니다.
2404* `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)에서는 대신 입력을 줄이거나 새 세션을 시작하라는 메시지가 표시됩니다.2451* `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)에서는 대신 입력을 줄이거나 새 세션을 시작하라는 메시지가 표시됩니다.
2405 2452
2406v2.1.212 이전에는 이미지가 충분히 누적된 대화가 매 턴마다 `Request too large (max 32MB). Double press esc to go back and try with a smaller file.`로 실패했습니다. v2.1.229 이전에는 압축으로 해결할 수 없는 경우에도 Claude Code가 모든 거부에 대해 첨부 파일 관련 안내를 표시했습니다.2453v2.1.212 이전에는 이미지가 충분히 누적된 대화가 매 턴마다 `Request too large (max 32MB). Double press esc to go back and try with a smaller file.`로 실패했습니다. v2.1.229 이전에는 압축으로 해결할 수 없는 경우에도 Claude Code가 모든 거부에 대해 첨부 파일 관련 조언을 표시했습니다.
2407 2454
2408**해결 방법:**2455**해결 방법:**
2409 2456
2410* 메시지에 `compacting cannot make it fit`이 표시되면 Esc를 두 번 눌러 큰 내용을 추가한 턴 이전으로 되돌아가거나, `/clear`를 실행하여 새로 시작합니다2457* 메시지에 `compacting cannot make it fit`이 표시되면 Esc를 두 번 눌러 큰 내용을 추가한 턴 이전으로 되돌아가거나, `/clear`를 실행하여 새로 시작하십시오
2411* 그렇지 않으면 누적된 이미지와 첨부 파일을 제거하는 `/compact`를 실행합니다2458* 그렇지 않으면 누적된 이미지와 첨부 파일을 제거하는 `/compact`를 실행하십시오
2412* 큰 파일은 내용을 붙여넣는 대신 경로로 참조하여 Claude가 나누어 읽을 수 있게 합니다2459* 큰 파일은 내용을 붙여넣는 대신 경로로 참조하여 Claude가 나누어 읽을 수 있도록 하십시오
2413* 이미지의 경우 아래의 [Image was too large](#image-was-too-large)를 참조하십시오2460* 이미지의 경우 아래의 [Image was too large](#image-was-too-large)를 참조하십시오
2414 2461
2415### Image was too large2462### Image was too large
2420Image was too large. Double press esc to go back and try again with a smaller image.2467Image was too large. Double press esc to go back and try again with a smaller image.
2421API Error: 400 ... image dimensions exceed max allowed size2468API Error: 400 ... image dimensions exceed max allowed size
2422API Error: an image in the conversation could not be processed and was removed.2469API Error: an image in the conversation could not be processed and was removed.
2470An 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.
2423```2471```
2424 2472
2425`could not be processed and was removed` 줄은 API가 대화 내의 이미지(예: 크기 또는 해상도 한도를 초과한 이미지)를 거부했다는 뜻입니다.2473`could not be processed and was removed` 줄은 크기 또는 해상도 한도를 초과하는 이미지 등 대화 내의 이미지를 API가 거부했다는 의미입니다.
2426 2474
2427이러한 오류 중 하나가 계속 발생하면 Claude Code를 업데이트하십시오. 이전 버전에서는 다음과 같은 이유로 이미지 오류가 반복될 수 있었습니다.2475이러한 오류 중 하나가 계속 반복된다면 Claude Code를 업데이트하십시오. 이전 버전에서는 다음과 같은 이유로 이미지 오류가 반복될 수 있었습니다.
2428 2476
2429* v2.1.299 이전에는 이미지가 많은 긴 대화에서 Claude Code가 한도를 초과한 이미지 대신 마지막으로 첨부한 이미지를 제거할 수 있었습니다. 그 결과 `was removed` 줄이 매 턴마다 반복되었고, Claude는 새 이미지를 볼 수 없었습니다.2477* v2.1.299 이전에는 이미지가 많은 긴 대화에서 Claude Code가 한도를 초과한 이미지 대신 마지막으로 첨부한 이미지를 제거할 수 있었습니다. 그러면 `was removed` 줄이 매 턴마다 반복되었고 Claude는 새 이미지를 보지 못했습니다.
2430* v2.1.299 이전에는 VS Code, Desktop 앱, Agent SDK에서 Claude가 작업하는 동안 첨부한 이미지가 다른 첨부 이미지와 달리 크기 조정되지 않았습니다. 이 이미지는 원래 크기 그대로 API에 전달되어 긴 대화에서 이미지 오류가 반복되었습니다.2478* v2.1.299 이전에는 VS Code, Desktop 앱, Agent SDK에서 Claude가 작업하는 동안 첨부한 이미지가 다른 첨부 이미지와 달리 크기 조정되지 않았습니다. 이 이미지들은 원래 크기 그대로 API에 전달되어 긴 대화에서 이미지 오류가 반복되었습니다.
2431* v2.1.166 이전에는 붙여넣은 이미지가 대화에 남아 이후 모든 메시지에서 같은 오류가 반복될 수 있었습니다2479* v2.1.166 이전에는 붙여넣은 이미지가 대화에 남아 이후 모든 메시지에서 같은 오류가 반복될 수 있었습니다
2432 2480
2433**해결 방법:**2481**해결 방법:**
2434 2482
2435* 붙여넣기 전에 이미지 크기를 줄입니다. API는 단일 이미지의 경우 긴 변 기준 최대 8000픽셀, 컨텍스트에 이미지가 20개를 초과하는 경우 최대 3000픽셀까지 허용합니다.2483* 붙여넣기 전에 이미지 크기를 조정하십시오. API는 단일 이미지의 경우 가장 긴 변 기준 8000픽셀까지, 컨텍스트에 이미지가 20개를 초과하는 경우 3000픽셀까지 허용합니다.
2436* 전체 화면 대신 관련 영역만 좁게 스크린샷을 찍습니다2484* 전체 화면 대신 관련 영역만 더 좁게 스크린샷을 찍으십시오
2485* `dimension limit for many-image requests` 메시지의 경우, 메시지에 `/compact`가 언급되어 있으면 Claude Code 프롬프트에서 이를 실행하거나, 이미지가 더 적은 새 세션을 시작하십시오
2486
2487`dimension limit for many-image requests` 메시지에는 API 오류에 명시된 픽셀 한도가 표시됩니다.
2437 2488
2438### Unable to resize image2489### Unable to resize image
2439 2490
2449Unable 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.2500Unable 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.
2450```2501```
2451 2502
2452Claude Code는 일반적으로 큰 이미지의 크기를 자동으로 조정합니다. 이러한 오류는 이미지를 디코딩하거나 API 한도에 맞게 크기를 조정할 수 없었다는 뜻입니다.2503Claude Code는 일반적으로 큰 이미지를 자동으로 크기 조정합니다. 이 오류들은 이미지를 디코딩할 수 없었거나 API 한도에 맞게 크기를 조정할 수 없었다는 의미입니다.
2453 2504
2454**해결 방법:**2505**해결 방법:**
2455 2506
2456* 메시지가 이미지 변환을 요청하면 PNG, JPEG, GIF 또는 WebP로 변환한 후 다시 첨부합니다. Claude Code는 이러한 형식의 경우 이미지를 디코딩하지 않고도 파일 헤더에서 해상도를 확인할 수 있습니다.2507* 메시지에서 이미지 변환을 요청하면 PNG, JPEG, GIF 또는 WebP로 변환한 후 다시 첨부하십시오. Claude Code는 이러한 형식에 대해 이미지를 디코딩하지 않고도 파일 헤더에서 해상도를 확인할 수 있습니다.
2457* 메시지가 해상도 또는 크기 한도를 보고하면, 첨부하기 전에 이미지를 해당 한도 이하로 크기 조정하거나 다시 압축합니다.2508* 메시지에 해상도 또는 크기 한도가 표시되면, 첨부하기 전에 해당 한도 이하로 이미지 크기를 조정하거나 다시 압축하십시오.
2458* 메시지가 CMYK JPEG, 애니메이션 WebP, 손상되었을 수 있는 파일과 같은 원인을 명시하면, 메시지가 제안하는 형식으로 이미지를 다시 저장한 후 다시 첨부합니다.2509* 메시지에 CMYK JPEG, 애니메이션 WebP, 손상되었을 수 있는 파일 등의 원인이 표시되면, 메시지가 제안하는 형식으로 이미지를 다시 저장한 후 다시 첨부하십시오.
2459 2510
2460### Request rejected as unprocessable by the model2511### Request rejected as unprocessable by the model
2461 2512
2462API가 모델이 처리할 수 없는 요청으로 판단하여 거부했습니다. 이 메시지는 API 자체의 메시지입니다.2513API가 모델이 처리할 수 없는 요청이라며 요청을 거부했습니다. 이 메시지는 API 자체의 메시지입니다.
2463 2514
2464```text theme={null}2515```text theme={null}
2465API Error: 400 Request rejected as unprocessable by the model (too many or oversized images, or unsupported parameters)2516API Error: 400 Request rejected as unprocessable by the model (too many or oversized images, or unsupported parameters)
2466```2517```
2467 2518
2468Claude Code는 거부된 요청에서 가장 오래된 이미지와 문서를 제거한 후 다시 보낼 수 있습니다. v2.1.290 이전에는 Claude Code가 이 거부에 대해 이미지를 제거하지 않았기 때문에, 이미지가 수백 개 누적된 긴 세션은 매 턴마다 이 오류로 실패할 수 있었습니다.2519Claude Code는 거부된 요청에서 가장 오래된 이미지와 문서를 제거한 후 다시 보낼 수 있습니다. v2.1.290 이전에는 Claude Code가 이 거부에 대해 이미지를 제거하지 않았기 때문에, 수백 개의 이미지가 누적된 긴 세션은 매 턴마다 이 오류로 실패할 수 있었습니다.
2469 2520
2470**해결 방법:**2521**해결 방법:**
2471 2522
2472* 이미지나 문서가 포함된 대화에서 이 메시지가 계속 나타나면 직접 제거하십시오. Esc를 두 번 눌러 해당 내용을 추가한 턴 이전으로 되돌아가거나, `/clear`를 실행하여 새로 시작합니다.2523* 이미지나 문서가 포함된 대화에서 메시지가 계속 나타나면 직접 제거하십시오. Esc를 두 번 눌러 이를 추가한 턴 이전으로 되돌아가거나, `/clear`를 실행하여 새로 시작하십시오.
2473 2524
2474### PDF 오류2525### PDF 오류
2475 2526
2476첨부한 PDF를 처리할 수 없었습니다. 여기에 표시된 메시지는 비대화형 형태이며, 대화형 세션에서는 대신 esc를 두 번 눌러 다시 시도하라는 안내가 표시됩니다.2527첨부한 PDF를 처리할 수 없습니다. 여기에는 메시지가 비대화형 형식으로 표시되어 있으며, 대화형 세션에서는 대신 esc를 두 번 눌러 다시 시도하라고 안내합니다.
2477 2528
2478```text theme={null}2529```text theme={null}
2479PDF too large (max 100 pages, 20MB). Try reading the file a different way (e.g., extract text with pdftotext).2530PDF too large (max 100 pages, 20MB). Try reading the file a different way (e.g., extract text with pdftotext).
2483 2534
2484**해결 방법:**2535**해결 방법:**
2485 2536
2486* 크기가 큰 PDF의 경우 파일 전체를 첨부하는 대신 Claude에게 Read 도구로 페이지 범위를 읽도록 요청하거나, `pdftotext` 같은 도구로 텍스트를 추출한 후 출력 파일을 경로로 참조합니다2537* 너무 큰 PDF의 경우, 전체 파일을 첨부하는 대신 Claude에게 Read 도구로 페이지 범위를 읽도록 요청하거나, `pdftotext` 같은 도구로 텍스트를 추출한 후 출력 파일을 경로로 참조하십시오
2487* 보호되었거나 유효하지 않은 PDF의 경우 비밀번호를 제거하거나 원본 애플리케이션에서 파일을 다시 내보낸 후 다시 시도합니다2538* 보호되었거나 유효하지 않은 PDF의 경우, 비밀번호를 제거하거나 원본 애플리케이션에서 파일을 다시 내보낸 후 다시 시도하십시오
2488 2539
2489Claude가 Read 도구로 PDF의 페이지 범위를 읽을 때, 다른 메시지와 함께 읽기가 실패할 수 있습니다.2540Claude가 Read 도구로 PDF의 페이지 범위를 읽을 때, 다른 메시지와 함께 읽기가 실패할 수 있습니다.
2490 2541
2492pdftoppm is not installed. Install poppler-utils (e.g. `brew install poppler` or `apt-get install poppler-utils`) to enable PDF page rendering.2543pdftoppm is not installed. Install poppler-utils (e.g. `brew install poppler` or `apt-get install poppler-utils`) to enable PDF page rendering.
2493```2544```
2494 2545
2495페이지 범위 읽기는 `pdftoppm`으로 페이지를 렌더링합니다. 메시지가 제시하는 명령으로 poppler-utils를 설치하거나, 다른 플랫폼에서는 `PATH`에 `pdftoppm`을 추가하는 poppler 빌드를 설치하십시오. 어떤 PDF가 페이지 범위로 읽히는지는 [Read 도구 동작](https://code.claude.com/docs/ko/tools-reference.md#read-tool-behavior)을 참조하십시오.2546페이지 범위 읽기는 `pdftoppm`으로 페이지를 렌더링합니다. 메시지에 제시된 명령으로 poppler-utils를 설치하거나, 다른 플랫폼에서는 `pdftoppm`을 `PATH`에 추가하는 poppler 빌드를 설치하십시오. 어떤 PDF가 페이지 범위로 읽히는지는 [Read 도구 동작](https://code.claude.com/docs/ko/tools-reference.md#read-tool-behavior)을 참조하십시오.
2496 2547
2497### Extra inputs are not permitted2548### Extra inputs are not permitted
2498 2549
2499요청을 받은 엔드포인트가 요청의 필드 중 하나를 허용하지 않는 입력으로 판단하여 거부했으며, 엔드포인트의 메시지에 해당 필드가 명시됩니다.2550요청을 받은 엔드포인트가 요청의 필드 중 하나를 허용하지 않는 입력으로 거부했으며, 엔드포인트의 메시지에 해당 필드가 표시됩니다.
2500 2551
2501```text theme={null}2552```text theme={null}
2502API Error: 400 ... context_management: Extra inputs are not permitted2553API Error: 400 ... context_management: Extra inputs are not permitted
2503```2554```
2504 2555
2505Claude 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)에서 두 경우를 모두 다룹니다.2556Claude 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)에서 두 경우를 모두 다룹니다.
2506 2557
2507**해결 방법:**2558**해결 방법:**
2508 2559
2509* 메시지에 `context_management: Extra inputs are not permitted`가 포함되어 있으면 [Claude Code를 v2.1.304 이상으로 업데이트](https://code.claude.com/docs/ko/setup.md#update-claude-code)하십시오. 업데이트 후에는 Claude Code가 이 거부에 대해 해당 필드 없이 요청을 한 번 더 보냅니다. v2.1.304 이전에는 Claude Code가 이 거부에 대해 재시도하지 않았습니다.2560* 메시지에 `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가 이 거부를 재시도하지 않았습니다.
2510* 메시지에 `defer_loading` 또는 `tool_reference`가 표시되면 Claude Code를 v2.1.305 이상으로 [업데이트](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).2561* 메시지에 `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).
2511* 게이트웨이가 헤더를 삭제하는 경우, `anthropic-beta` 헤더를 전달하도록 게이트웨이를 구성하십시오. 게이트웨이가 전달해야 하는 항목은 [기능 패스스루](https://code.claude.com/docs/ko/llm-gateway-protocol.md#feature-pass-through)를 참조하십시오.2562* 게이트웨이가 헤더를 누락한다면 `anthropic-beta` 헤더를 전달하도록 구성하십시오. 게이트웨이가 전달해야 하는 항목은 [기능 패스스루](https://code.claude.com/docs/ko/llm-gateway-protocol.md#feature-pass-through)를 참조하십시오.
2512* 대안으로, 실행하기 전에 [`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)에서 다룹니다.2563* 대안으로, 실행하기 전에 [`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)에서 다룹니다.
2513 2564
2514v2.1.302 이전에는 게이트웨이가 관여하지 않아도 이 오류가 `diagnostics` 필드를 명시할 수 있었습니다. 이는 이미 Anthropic API를 사용한 세션이 재시작 없이 Amazon Bedrock 또는 Google Cloud's Agent Platform으로 전환될 때 발생했습니다. 예를 들어 열어 둔 세션은 다른 Claude Code 창에서 [`/setup-bedrock`](https://code.claude.com/docs/ko/commands)을 실행하면 Bedrock으로 전환됩니다. 해당 버전에서는 그 세션에서 `/clear`를 실행하거나 세션을 재시작하십시오.2565v2.1.302 이전에는 게이트웨이가 관여하지 않아도 이 오류에 `diagnostics` 필드가 표시될 수 있었습니다. 이는 이미 Anthropic API를 사용한 세션이 재시작 없이 Amazon Bedrock 또는 Google Cloud의 Agent Platform으로 전환될 때 나타났습니다. 예를 들어, 다른 Claude Code 창에서 [`/setup-bedrock`](https://code.claude.com/docs/ko/commands)을 실행하면 열어 둔 세션이 Bedrock으로 전환됩니다. 해당 버전에서는 그 세션에서 `/clear`를 실행하거나 세션을 재시작하십시오.
2515 2566
2516### Tool input schema is invalid2567### Tool input schema is invalid
2517 2568
2518요청에 포함된 도구가 API의 JSON Schema 검증을 통과하지 못하는 `input_schema`를 선언했기 때문에 API가 요청 전체를 거부했습니다. `tools.` 뒤의 숫자는 요청의 도구 목록에서 실패한 도구의 위치이며, 조회할 수 있는 이름이 아닙니다.2569요청에 포함된 도구가 API의 JSON Schema 검증에 실패하는 `input_schema`를 선언했기 때문에 API가 요청 전체를 거부했습니다. `tools.` 뒤의 숫자는 요청의 도구 목록에서 실패한 도구의 위치이며, 조회할 수 있는 이름이 아닙니다.
2519 2570
2520```text theme={null}2571```text theme={null}
2521API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid2572API Error: 400 ... tools.N.custom.input_schema: JSON schema is invalid
2522API Error: 400 ... tools.N.custom.input_schema.properties: Property keys should match pattern '^[a-zA-Z0-9_.-]{1,64}$'2573API Error: 400 ... tools.N.custom.input_schema.properties: Property keys should match pattern '^[a-zA-Z0-9_.-]{1,64}$'
2523```2574```
2524 2575
2525첫 번째 형태는 스키마가 유효한 JSON Schema draft 2020-12가 아니라는 뜻입니다. 두 번째 형태는 최상위 속성 이름이 메시지에 인용된 패턴과 일치하지 않는다는 뜻입니다.2576첫 번째 형식은 스키마가 유효한 JSON Schema draft 2020-12가 아니라는 의미입니다. 두 번째 형식은 최상위 속성 이름이 메시지에 인용된 패턴과 일치하지 않는다는 의미입니다.
2526 2577
2527Claude Code는 서버의 도구를 로드할 때 [입력 스키마가 이 검증에 실패할 MCP 도구를 제외](https://code.claude.com/docs/ko/mcp.md#tools-with-invalid-input-schemas)하므로, 일반적으로 요청에 그런 도구가 포함되지 않습니다.2578Claude Code는 서버의 도구를 로드할 때 [입력 스키마가 이 검증에 실패할 MCP 도구를 제외](https://code.claude.com/docs/ko/mcp.md#tools-with-invalid-input-schemas)하므로, 일반적으로 요청에는 그런 도구가 포함되지 않습니다.
2528 2579
2529[플래그 가져오기가 꺼진 배포](https://code.claude.com/docs/ko/env-vars.md#features-that-need-feature-flag-fetching)나 플래그를 한 번도 받지 못한 머신에서는 Claude Code가 어떤 도구가 거부될지를 서버 로그에 기록하지만 그래도 해당 도구를 보내므로, 이 오류가 여전히 발생할 수 있습니다.2580[플래그 가져오기가 꺼진 배포](https://code.claude.com/docs/ko/env-vars.md#features-that-need-feature-flag-fetching)나 플래그를 한 번도 받지 못한 머신에서는, Claude Code가 어떤 도구가 거부될지 서버 로그에 기록하지만 그래도 해당 도구를 보내므로 이 오류가 여전히 발생할 수 있습니다.
2530 2581
2531스키마가 `$schema`에서 draft 2020-12 이외의 JSON Schema 방언을 선언한 도구에서도 이 오류가 발생할 수 있습니다. Claude Code는 이러한 스키마를 JSON Schema 메타 스키마와 대조하여 검사하지 않지만, 최상위 속성 이름 검사는 여전히 적용됩니다.2582이 오류는 스키마가 `$schema`에서 draft 2020-12 이외의 JSON Schema 방언을 선언한 도구에 대해서도 발생할 수 있습니다. Claude Code는 이러한 스키마를 JSON Schema 메타 스키마와 대조하여 확인하지 않지만, 최상위 속성 이름 검사는 여전히 적용됩니다.
2532 2583
2533v2.1.216 이전에는 어떤 배포에서도 제외 검사가 실행되지 않았습니다.2584v2.1.216 이전에는 어떤 배포에서도 제외 검사가 실행되지 않았습니다.
2534 2585
2535**해결 방법:**2586**해결 방법:**
2536 2587
2537* 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)하지 않았기 때문에, 해당 도구가 포함된 모든 요청에서 이 오류가 반복되었습니다.2588* 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)하지 않았기 때문에, 해당 도구가 포함된 모든 요청에서 이 오류가 반복되었습니다.
2538* 유효하지 않은 스키마를 선언한 MCP 서버를 제거하거나 [비활성화](https://code.claude.com/docs/ko/mcp.md#disable-a-server-without-removing-it)합니다. 오류는 도구를 위치로만 표시합니다. v2.1.216 이상에서는 각 서버의 로그에서 입력 스키마가 거부될 도구를 명시하는 줄을 확인하십시오. 해당 도구를 명시하는 로그가 없으면 서버를 하나씩 비활성화해 보십시오.2589* 유효하지 않은 스키마를 선언하는 MCP 서버를 제거하거나 [비활성화](https://code.claude.com/docs/ko/mcp.md#disable-a-server-without-removing-it)하십시오. 오류는 도구를 위치로만 표시합니다. v2.1.216 이상에서는 각 서버의 로그에서 입력 스키마가 거부될 도구를 명시하는 줄을 확인하십시오. 어떤 로그에도 해당 도구가 명시되어 있지 않다면 서버를 하나씩 비활성화하십시오.
2539* 서버를 직접 관리한다면 도구의 `input_schema`를 수정하십시오. 스키마는 유효한 JSON Schema여야 하며, 최상위 속성 이름은 1\~64자 길이에 ASCII 문자와 숫자, `_`, `.`, `-`만 사용해야 합니다. [입력 스키마가 유효하지 않은 도구](https://code.claude.com/docs/ko/mcp.md#tools-with-invalid-input-schemas)를 참조하십시오.2590* 서버를 직접 관리한다면 도구의 `input_schema`를 수정하십시오. 스키마는 유효한 JSON Schema여야 하며, 최상위 속성 이름은 1\~64자여야 하고 ASCII 문자와 숫자, `_`, `.`, `-`만 사용해야 합니다. [유효하지 않은 입력 스키마를 가진 도구](https://code.claude.com/docs/ko/mcp.md#tools-with-invalid-input-schemas)를 참조하십시오.
2540 2591
2541### 128자를 초과하는 MCP 도구 이름2592### 128자를 초과하는 MCP 도구 이름
2542 2593
2543MCP 서버가 `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`의 디버그 로그에 다음 메시지를 기록합니다.2594MCP 서버가 나열한 도구의 전체 이름(예: `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`의 디버그 로그에 다음 메시지를 기록합니다.
2544 2595
2545```text theme={null}2596```text theme={null}
2546Tool "mcp__<server>__<tool>" is not sent to Claude: its name has <N> characters and the API accepts at most 1282597Tool "mcp__<server>__<tool>" is not sent to Claude: its name has <N> characters and the API accepts at most 128
2549**해결 방법:**2600**해결 방법:**
2550 2601
2551* 서버를 직접 관리한다면 도구 이름을 줄이십시오.2602* 서버를 직접 관리한다면 도구 이름을 줄이십시오.
2552* 서버가 [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)처럼 이전 이름으로 서버나 도구를 참조하는 항목을 업데이트하십시오.2603* 서버가 [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)처럼 이전 이름으로 서버나 도구를 참조하는 항목을 업데이트하십시오.
2553* [플러그인이 서버를 번들로 포함](https://code.claude.com/docs/ko/mcp.md#plugin-provided-mcp-servers)하는 경우 도구의 전체 이름에 플러그인 이름도 포함됩니다. 플러그인 관리자에게 서버 또는 도구 이름을 줄여 달라고 요청하십시오.2604* [플러그인이 서버를 번들로 제공](https://code.claude.com/docs/ko/mcp.md#plugin-provided-mcp-servers)하는 경우, 도구의 전체 이름에 플러그인 이름도 포함됩니다. 플러그인 관리자에게 서버 또는 도구 이름을 줄여 달라고 요청하십시오.
2554 2605
2555v2.1.292 이전에는 Claude Code가 그래도 도구를 보냈고, API는 해당 도구가 포함된 모든 요청을 `API Error: 400 ... tools.N.custom.name: String should have at most 128 characters`로 거부했습니다.2606v2.1.292 이전에는 Claude Code가 그래도 해당 도구를 보냈고, API는 이를 포함한 모든 요청을 `API Error: 400 ... tools.N.custom.name: String should have at most 128 characters`로 거부했습니다.
2556 2607
2557### 200자를 초과하는 tool\_use.name2608### 200자를 초과하는 tool\_use.name
2558 2609
2559대화 기록의 도구 호출이 API가 요청에서 허용하는 200자보다 긴 이름을 가지고 있습니다.2610대화 기록의 도구 호출에 API가 요청에서 허용하는 200자보다 긴 이름이 포함되어 있습니다.
2560 2611
2561```text theme={null}2612```text theme={null}
2562API Error: 400 ... tool_use.name: String should have at most 200 characters2613API Error: 400 ... tool_use.name: String should have at most 200 characters
2566 2617
2567**해결 방법:**2618**해결 방법:**
2568 2619
2569* `claude update`를 실행한 후 대화를 재개합니다. 업데이트된 버전은 트랜스크립트를 로드할 때 너무 긴 이름을 복구하므로, 멈춰 있던 대화가 다시 작동합니다.2620* `claude update`를 실행한 후 대화를 재개하십시오. 업데이트된 버전은 트랜스크립트를 로드할 때 너무 긴 이름을 복구하므로, 멈춰 있던 대화가 다시 작동합니다.
2570 2621
2571v2.1.281 이전에는 너무 긴 이름이 기록에 남아 API가 `/compact`와 `--resume`을 포함하여 대화를 다시 보내는 모든 요청을 거부했기 때문에, 이 오류가 반복되고 대화가 멈춰 있었습니다.2622v2.1.281 이전에는 너무 긴 이름이 기록에 남아 있어 API가 `/compact`와 `--resume`을 포함하여 대화를 다시 보내는 모든 요청을 거부했기 때문에, 이 오류가 반복되고 대화가 멈춰 있었습니다.
2572 2623
2573### There's an issue with the selected model2624### There's an issue with the selected model
2574 2625
2575구성된 모델 이름이 인식되지 않았거나 계정에 해당 모델에 대한 액세스 권한이 없습니다. v2.1.160부터 끝부분의 힌트(여기서는 대화형 형태로 표시)는 사용 환경에 따라 다릅니다.2626구성된 모델 이름을 인식할 수 없거나 계정에 해당 모델에 대한 접근 권한이 없습니다. v2.1.160부터 끝부분의 힌트(여기서는 대화형 형식으로 표시됨)는 사용 환경에 따라 다릅니다.
2576 2627
2577```text theme={null}2628```text theme={null}
2578There'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.2629There'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.
2580 2631
2581**해결 방법:**2632**해결 방법:**
2582 2633
2583* **대화형 CLI**: `/model`을 실행하여 계정에서 사용할 수 있는 모델 중에서 선택합니다.2634* **대화형 CLI**: `/model`을 실행하여 계정에서 사용할 수 있는 모델 중에서 선택하십시오.
2584* **비대화형 모드(`-p`)**: 유효한 별칭이나 ID와 함께 `--model`을 전달하거나 [`ANTHROPIC_MODEL`](https://code.claude.com/docs/ko/env-vars)을 설정합니다. 이 사용 환경에서는 오류 텍스트에 `Run --model`이 표시됩니다.2635* **비대화형 모드(`-p`)**: 유효한 별칭 또는 ID와 함께 `--model`을 전달하거나, [`ANTHROPIC_MODEL`](https://code.claude.com/docs/ko/env-vars)을 설정하십시오. 이 사용 환경에서는 오류 텍스트에 `Run --model`이 표시됩니다.
2585* **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` 오류를 처리하여 자체 재시도나 모델 선택기를 제공하십시오.2636* **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` 오류를 처리하여 자체 재시도 또는 모델 선택기를 표시하십시오.
2586* 버전이 포함된 전체 ID 대신 `sonnet`이나 `opus` 같은 별칭을 사용하십시오. 별칭은 관리되는 기본값으로 해석되므로 오래되지 않습니다. [모델 구성](https://code.claude.com/docs/ko/model-config.md)을 참조하십시오.2637* 전체 버전 ID 대신 `sonnet`이나 `opus` 같은 별칭을 사용하십시오. 별칭은 관리되는 기본값으로 해석되므로 오래되어 쓸모없어지지 않습니다. [모델 구성](https://code.claude.com/docs/ko/model-config.md)을 참조하십시오.
2587* CLI에서 잘못된 모델이 계속 다시 나타난다면 어딘가에 오래된 ID가 설정되어 있는 것입니다. 모델을 설정할 수 있는 위치를 [우선순위 순서](https://code.claude.com/docs/ko/model-config.md#setting-your-model)대로 확인하고 오래된 값을 제거하십시오.2638* CLI에서 잘못된 모델이 계속 돌아온다면 어딘가에 오래된 ID가 설정되어 있는 것입니다. [우선순위 순서](https://code.claude.com/docs/ko/model-config.md#setting-your-model)대로 모델을 설정할 수 있는 위치를 확인하고 오래된 값을 제거하십시오.
2588* Claude Code는 만료된 claude.ai 로그인을 이 오류가 아닌 [Login expired](#login-expired)로 보고합니다. v2.1.206 이전에는 더 이상 갱신할 수 없는 만료된 로그인이 모든 모델에서 이 오류로 실패했습니다. 이전 버전에서 이 현상이 나타나면 `/login`을 실행하십시오.2639* Claude Code는 만료된 claude.ai 로그인을 이 오류가 아닌 [Login expired](#login-expired)로 보고합니다. v2.1.206 이전에는 더 이상 갱신할 수 없는 만료된 로그인으로 인해 모든 모델이 이 오류로 실패했습니다. 이전 버전에서 이 현상이 나타나면 `/login`을 실행하십시오.
2589* [`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`로 켜지 않는 한 게이트웨이 뒤에서 도구 검색이 꺼져 있었습니다.2640* [`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`로 켜지 않는 한 게이트웨이 뒤에서 도구 검색이 꺼져 있었습니다.
2590* Google Cloud's Agent Platform 배포의 경우 [Google Cloud's Agent Platform 문제 해결](https://code.claude.com/docs/ko/google-vertex-ai.md#troubleshooting)을 참조하십시오.2641* Google Cloud의 Agent Platform 배포의 경우 [Google Cloud의 Agent Platform 문제 해결](https://code.claude.com/docs/ko/google-vertex-ai.md#troubleshooting)을 참조하십시오.
2591 2642
2592### Model is not a recognized model id2643### Model is not a recognized model id
2593 2644
2594모델 전환에 전달한 문자열을 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)로 실패했습니다.2645모델 전환에 전달한 문자열이 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)로 실패했습니다.
2595 2646
2596```text theme={null}2647```text theme={null}
2597Model "Sonnet5" is not a recognized model id. Did you mean 'claude-sonnet-5'?2648Model "Sonnet5" is not a recognized model id. Did you mean 'claude-sonnet-5'?
2598```2649```
2599 2650
2600이 예에서는 앱이 표시 이름 `Sonnet 5`를 보냈고, 메시지는 이를 공백 없이 반복합니다. 끝부분의 힌트는 가장 가깝게 일치하는 별칭이나 모델 ID를 표시합니다. 충분히 가까운 항목이 없으면 대신 `Run /model to see available models.`가 표시됩니다. [Desktop 앱](https://code.claude.com/docs/ko/desktop.md)이 시작한 세션에서는 일치 항목이 없을 때의 힌트가 `Switch to a different model.`로 표시됩니다.2651이 예에서는 앱이 표시 이름 `Sonnet 5`를 보냈으며, 메시지는 이를 공백 없이 반복합니다. 끝부분의 힌트는 가장 가깝게 일치하는 별칭 또는 모델 ID를 표시합니다. 충분히 가까운 것이 없으면 대신 `Run /model to see available models.`로 표시됩니다. [Desktop 앱](https://code.claude.com/docs/ko/desktop.md)이 대신 시작한 세션에서는 일치하는 항목이 없을 때의 힌트가 `Switch to a different model.`로 표시됩니다.
2601 2652
2602Anthropic API에서 Agent SDK나 앱을 통해 전환할 때는 표시 이름이나 빈 문자열처럼 모델 ID가 될 수 없는 문자열만 이 오류가 발생합니다.2653Anthropic API에서 Agent SDK나 앱을 통해 전환하는 경우, 표시 이름이나 빈 문자열처럼 모델 ID가 될 수 없는 문자열만 이 오류를 받습니다.
2603 2654
2604Remote Control 기기에서 모델을 선택하면 Claude Code가 문자열을 로컬에서 검사합니다. 모델 별칭, Claude Code가 나열하거나 사용자가 구성한 모델, 또는 `claude-`로 시작하는 ID가 아닌 모든 문자열은 이 오류가 발생하며, `claud-sonnet-5` 같은 오타가 있는 ID도 포함됩니다. v2.1.260 이전에는 이 검사가 Remote Control 선택을 다루지 않았기 때문에, 인식되지 않은 문자열이 적용된 후 다음 요청에서 실패했습니다.2655Remote Control 기기에서 모델을 선택하면 Claude Code가 문자열을 로컬에서 확인합니다. 모델 별칭, Claude Code가 나열하거나 사용자가 구성한 모델, 또는 `claude-`로 시작하는 ID가 아닌 모든 문자열은 `claud-sonnet-5`처럼 잘못 입력한 ID를 포함하여 이 오류를 받습니다. v2.1.260 이전에는 이 검사가 Remote Control 선택에 적용되지 않았으므로, 인식되지 않는 문자열이 적용된 후 다음 요청에서 실패했습니다.
2605 2656
2606**해결 방법:**2657**해결 방법:**
2607 2658
2608* 인수 없이 `/model`을 실행하여 선택기를 열고 계정에서 사용할 수 있는 모델 중에서 선택한 후, 그곳에 표시된 별칭이나 ID를 전달합니다2659* 인수 없이 `/model`을 실행하여 선택기를 열고 계정에서 사용할 수 있는 모델 중에서 선택한 후, 그곳에 표시된 별칭 또는 ID를 전달하십시오
2609* 최신 Claude Code 버전에서만 지원하는 별칭을 사용한 경우 `claude update`를 실행하거나 대신 모델의 전체 ID를 전달합니다. 서버는 여전히 해당 모델에 대해 최소 Claude Code 버전을 요구할 수 있습니다. [Claude Code does not support this model](#claude-code-does-not-support-this-model)을 참조하십시오.2660* 최신 Claude Code 버전에서만 지원하는 별칭을 사용했다면 `claude update`를 실행하거나, 대신 모델의 전체 ID를 전달하십시오. 서버는 여전히 해당 모델에 대해 최소 Claude Code 버전을 요구할 수 있습니다. [Claude Code does not support this model](#claude-code-does-not-support-this-model)을 참조하십시오.
2610* v2.1.200 이전에 저장된 모델은 이 검사로 복구되지 않습니다. 오래된 값이 계속 다시 나타나면 [모델 설정](https://code.claude.com/docs/ko/model-config.md#setting-your-model)에 나열된 위치에서 제거하십시오.2661* v2.1.200 이전에 저장된 모델은 이 검사로 복구되지 않습니다. 오래된 값이 계속 돌아온다면 [모델 설정](https://code.claude.com/docs/ko/model-config.md#setting-your-model)에 나열된 위치에서 제거하십시오.
2611* Anthropic API 이외의 공급자에서, 또는 게이트웨이나 사용자 지정 `ANTHROPIC_BASE_URL` 뒤에서는 빈 문자열만 이 오류가 발생합니다. Claude Code는 모든 공급자에서 요청 시점에 [인식되지 않은 모델 진단 줄](#unrecognized-model-id-on-a-request)을 여전히 기록할 수 있습니다.2662* Anthropic API 이외의 제공업체, 또는 게이트웨이나 사용자 지정 `ANTHROPIC_BASE_URL` 뒤에서는 빈 문자열만 이 오류를 받습니다. Claude Code는 모든 제공업체에서 요청 시점에 [인식되지 않는 모델 진단 줄](#unrecognized-model-id-on-a-request)을 여전히 기록할 수 있습니다.
2612 2663
2613### Model not found2664### Model not found
2614 2665
2615이름으로 모델을 전환했지만 Claude Code가 해당 이름의 모델이 존재하는지 확인할 수 없었습니다. 이름이 [모델 별칭](https://code.claude.com/docs/ko/model-config.md#model-aliases)이나 Claude Code가 로컬에서 허용하는 다른 표기가 아닌 경우, Claude Code는 최소한의 API 요청으로 이를 확인하며, 이 오류는 보통 API 엔드포인트의 응답입니다. `/model <name>`에서 공백이 포함된 이름처럼 모델 ID가 될 수 없는 이름은 같은 메시지가 표시됩니다.2666이름으로 모델을 전환했지만 Claude Code가 해당 이름의 모델이 존재하는지 확인할 수 없었습니다. 이름이 [모델 별칭](https://code.claude.com/docs/ko/model-config.md#model-aliases)이나 Claude Code가 로컬에서 허용하는 다른 표기가 아니면, Claude Code는 최소한의 API 요청으로 이를 확인하며, 이 오류는 대개 API 엔드포인트의 응답입니다. `/model <name>`의 경우, 공백이 포함된 이름처럼 모델 ID가 전혀 될 수 없는 이름도 같은 메시지를 받습니다.
2616 2667
2617```text theme={null}2668```text theme={null}
2618Model 'claude-opus-9' not found2669Model 'claude-opus-9' not found
2619```2670```
2620 2671
2621공급자별 모델 ID를 사용하는 공급자에서는 메시지에 공급자의 대체 모델 ID를 명시하는 `Try '...' instead` 제안이 추가될 수 있습니다.2672제공업체별 모델 ID를 사용하는 제공업체에서는 메시지에 폴백 모델에 대한 해당 제공업체의 ID를 알려 주는 `Try '...' instead` 제안이 추가될 수 있습니다.
2622 2673
2623**해결 방법:**2674**해결 방법:**
2624 2675
2625* 인수 없이 `/model`을 실행하고 계정에서 사용할 수 있는 모델 중에서 선택하거나, 관리되는 기본값으로 해석되는 `sonnet` 같은 [모델 별칭](https://code.claude.com/docs/ko/model-config.md#model-aliases)을 사용합니다2676* 인수 없이 `/model`을 실행하여 계정에서 사용할 수 있는 모델 중에서 선택하거나, 관리되는 기본값으로 해석되는 `sonnet` 같은 [모델 별칭](https://code.claude.com/docs/ko/model-config.md#model-aliases)을 사용하십시오
2626* 전체 ID를 입력했다면 공급자의 모델 카탈로그와 대조하여 확인합니다. 새로 출시된 모델은 공급자나 리전에서 제공되기 전에 Anthropic API에서 먼저 사용 가능할 수 있습니다.2677* 전체 ID를 입력했다면 제공업체의 모델 카탈로그와 대조하여 확인하십시오. 새로 출시된 모델은 제공업체나 리전에서 제공하기 전에 Anthropic API에서 먼저 사용 가능할 수 있습니다.
2627* Agent SDK에서는 `setModel()`이 이 메시지로 실패하고 세션은 이전 모델로 계속 실행됩니다. TypeScript SDK에서는 [`supportedModels()`](https://code.claude.com/docs/ko/agent-sdk/typescript#query-object)를 호출하여 전환할 수 있는 모델 목록을 확인하십시오.2678* Agent SDK에서는 `setModel()`이 이 메시지와 함께 실패하고 세션은 이전 모델로 계속 실행됩니다. TypeScript SDK에서는 [`supportedModels()`](https://code.claude.com/docs/ko/agent-sdk/typescript#query-object)를 호출하여 전환할 수 있는 모델 목록을 확인하십시오.
2628* v2.1.265 이전에는 `/model`이 `opusplan[1m]` 별칭 표기도 이 오류로 거부했습니다. 해당 버전에서는 Claude Code를 업데이트하거나 대신 [설정](https://code.claude.com/docs/ko/model-config.md#setting-your-model) 또는 `--model`로 모델을 설정하십시오.2679* v2.1.265 이전에는 `/model`이 `opusplan[1m]` 별칭 표기도 이 오류로 거부했습니다. 해당 버전에서는 Claude Code를 업데이트하거나, 대신 [설정](https://code.claude.com/docs/ko/model-config.md#setting-your-model)에서 또는 `--model`로 모델을 설정하십시오.
2629 2680
2630### Couldn't confirm model with the API2681### Couldn't confirm model with the API
2631 2682
2632[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초 이내에 응답을 받지 못했습니다. 세션은 현재 모델을 유지합니다.2683[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초 이내에 응답을 받지 못했습니다. 세션은 현재 모델을 유지합니다.
2633 2684
2634```text theme={null}2685```text theme={null}
2635Couldn't confirm model "claude-sonnet-5" with the API. Try again, or run /model to see available models.2686Couldn't confirm model "claude-sonnet-5" with the API. Try again, or run /model to see available models.
2636```2687```
2637 2688
2638[Desktop 앱](https://code.claude.com/docs/ko/desktop.md)이 시작한 세션에서는 메시지가 `Try again.`에서 끝납니다.2689[Desktop 앱](https://code.claude.com/docs/ko/desktop.md)이 대신 시작한 세션에서는 메시지가 `Try again.`으로 끝납니다.
2639 2690
2640**해결 방법:**2691**해결 방법:**
2641 2692
2642* 모델로 다시 전환합니다2693* 모델로 다시 전환하십시오
2643* 전환이 계속 실패하면 Claude Code가 API 엔드포인트에 연결할 수 있는지 확인하십시오. [네트워크 및 연결 오류](#network-and-connection-errors)를 참조하십시오2694* 전환이 계속 실패하면 Claude Code가 API 엔드포인트에 연결할 수 있는지 확인하십시오. [네트워크 및 연결 오류](#network-and-connection-errors)를 참조하십시오
2644 2695
2645### 선택한 모델 확인 중 API 오류2696### 선택한 모델을 확인할 때 발생하는 API 오류
2646 2697
2647`/model <name>`으로 모델을 선택했거나, 세션에 연결된 앱이 전환을 요청했습니다. API가 속도 제한이나 서버 오류처럼 별도 항목이 없는 이유로, Claude Code가 모델 확인을 위해 보내는 최소한의 요청을 거부했습니다. 세션은 현재 모델을 유지하며, 메시지 끝에 그 사실이 표시됩니다.2698`/model <name>`으로 모델을 선택했거나, 세션에 연결된 앱이 전환을 요청했습니다. API가 속도 제한이나 서버 오류처럼 별도 항목이 없는 이유로 Claude Code가 모델 확인을 위해 보내는 최소한의 요청을 거부했습니다. 세션은 현재 모델을 유지하며, 메시지 끝에 그 사실이 표시됩니다.
2648 2699
2649```text theme={null}2700```text theme={null}
2650API error: 429 <the server's explanation> · model not changed2701API error: 429 <the server's explanation> · model not changed
2654 2705
2655**해결 방법:**2706**해결 방법:**
2656 2707
2657* 서버의 설명에 따라 조치합니다. 속도 제한이나 5xx 상태인 경우 잠시 기다린 후 모델을 다시 선택합니다2708* 서버의 설명에 따라 조치하십시오. 속도 제한이나 5xx 상태의 경우 잠시 기다린 후 모델을 다시 선택하십시오
2658* 고유한 문구가 있는 거부는 [Model not found](#model-not-found)와 [Model is restricted by your organization's settings](#model-is-restricted-by-your-organizations-settings) 같은 주변 항목에서 다룹니다2709* 고유한 문구가 있는 거부는 [Model not found](#model-not-found)와 [Model is restricted by your organization's settings](#model-is-restricted-by-your-organizations-settings) 같은 주변 항목에서 다룹니다
2659 2710
2660### Claude Opus is not available with the Claude Pro plan2711### Claude Opus is not available with the Claude Pro plan
2669 2720
2670**해결 방법:**2721**해결 방법:**
2671 2722
2672* `/model`을 실행하고 플랜에 포함된 모델을 선택합니다2723* `/model`을 실행하여 플랜에 포함된 모델을 선택하십시오
2673* 최근에 플랜을 업그레이드했는데도 이 메시지가 나타나면 `/logout`을 실행한 후 `/login`을 실행합니다. 저장된 토큰은 로그인 시점의 플랜을 반영하므로, claude.ai에서 업그레이드해도 다시 인증하기 전까지 기존 세션에는 적용되지 않습니다.2724* 최근에 플랜을 업그레이드했는데도 이 메시지가 표시된다면 `/logout`을 실행한 후 `/login`을 실행하십시오. 저장된 토큰은 로그인한 시점의 플랜을 반영하므로, claude.ai에서 업그레이드해도 다시 인증하기 전까지는 기존 세션에 적용되지 않습니다.
2674* 각 플랜에 포함된 모델은 [claude.com/pricing](https://claude.com/pricing)을 참조하십시오2725* 각 플랜에 포함된 모델은 [claude.com/pricing](https://claude.com/pricing)을 참조하십시오
2675 2726
2676### Claude Code does not support this model2727### Claude Code does not support this model
2677 2728
2678Claude Code 버전이 요구되는 최소 버전보다 낮아서 API가 400으로 요청을 거부했습니다. 선택한 모델이 서버가 모델별로 검사하는 더 새로운 버전을 요구하거나, 조직 정책이 특정 버전을 요구하는 경우입니다. 400에는 오류 코드 `claude_code_version_too_old`가 포함되며, 메시지에 어떤 최소 버전이 적용되는지 표시됩니다.2729Claude Code 버전이 요구되는 최소 버전보다 낮기 때문에 API가 400으로 요청을 거부했습니다. 선택한 모델이 더 새로운 버전을 요구하거나(서버가 모델별로 확인함), 조직의 정책이 이를 요구하는 경우입니다. 400에는 오류 코드 `claude_code_version_too_old`가 포함되며, 메시지에는 어떤 최소 버전이 적용되는지 표시됩니다.
2679 2730
2680```text theme={null}2731```text theme={null}
2681API 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.2732API 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.
2687API 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.2738API 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.
2688```2739```
2689 2740
2690API가 검사하는 버전은 요청을 보낸 Claude Code 바이너리가 보고하는 버전입니다.2741API가 확인하는 버전은 요청을 보낸 Claude Code 바이너리가 보고한 버전입니다.
2691 2742
2692**해결 방법:**2743**해결 방법:**
2693 2744
2697| :- | :- |2748| :- | :- |
2698| 직접 설치한 Claude Code | `claude update` 실행 |2749| 직접 설치한 Claude Code | `claude update` 실행 |
2699| Claude desktop 앱 | 앱 업데이트 |2750| Claude desktop 앱 | 앱 업데이트 |
2700| [VS Code 확장](https://code.claude.com/docs/ko/vs-code.md)에 번들로 포함된 바이너리 | 확장 업데이트 |2751| [VS Code 확장 프로그램](https://code.claude.com/docs/ko/vs-code.md)에 번들로 포함된 바이너리 | 확장 프로그램 업데이트 |
2701| 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)의 경우 다시 빌드합니다 |2752| 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)의 경우 다시 빌드 |
2702 2753
2703* [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)으로 채널이나 버전을 고정한 경우 관리자에게 변경을 요청하십시오2754* [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)으로 채널이나 버전을 고정한 경우 관리자에게 변경을 요청하십시오
2704* 모델별 문구의 경우 다른 모델로 전환하여 현재 세션에서 계속 작업할 수 있습니다. 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)을 호출하십시오2755* 모델별 문구의 경우, 다른 모델로 전환하여 현재 세션에서 계속 작업할 수 있습니다. 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)을 호출하십시오
2705* 조직 정책 문구의 경우 계속하기 전에 업데이트하십시오2756* 조직 정책 문구의 경우, 계속하기 전에 업데이트하십시오
2706 2757
2707### Model is restricted by your organization's settings2758### Model is restricted by your organization's settings
2708 2759
2709조직 관리자가 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 관리 콘솔에서 세션이 실행 중인 모델을 비활성화하면 세션 도중에도 대체 알림이 표시될 수 있습니다.2760조직 관리자가 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 관리 콘솔에서 세션이 실행 중인 모델을 비활성화하면, 대체 알림이 세션 도중에도 나타날 수 있습니다.
2710 2761
2711```text theme={null}2762```text theme={null}
2712Model "claude-opus-4-8" is restricted by your organization's settings. Using claude-sonnet-4-6 instead.2763Model "claude-opus-4-8" is restricted by your organization's settings. Using claude-sonnet-4-6 instead.
2713```2764```
2714 2765
2715제한된 모델에 대해 `/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.`입니다.2766제한된 모델에 대해 `/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.`입니다.
2716 2767
2717에이전트, 스킬 또는 명령 이름이 앞에 붙은 알림은 제한이 해당 [서브에이전트가 요청한 모델](https://code.claude.com/docs/ko/sub-agents.md#choose-a-model)에 적용되었다는 뜻입니다. 서브에이전트는 대체된 모델에서 실행되고 세션의 모델은 변경되지 않습니다. v2.1.223 이전에는 Claude Code가 Agent 도구로 실행된 서브에이전트에 대해서만 이 알림을 표시했습니다.2768알림 앞에 에이전트, 스킬 또는 명령 이름이 붙어 있다면 제한이 해당 [서브에이전트가 요청한 모델](https://code.claude.com/docs/ko/sub-agents.md#choose-a-model)에 적용되었다는 의미입니다. 서브에이전트는 대체된 모델로 실행되고 세션의 모델은 변경되지 않습니다. v2.1.223 이전에는 Claude Code가 Agent 도구로 실행된 서브에이전트에 대해서만 알림을 표시했습니다.
2718 2769
2719Claude 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 이전에는 같은 패밀리의 이전 버전이 허용되더라도 패밀리 별칭이 최신 버전만을 기준으로 대체되거나 거부되었습니다.2770Claude 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 이전에는 같은 계열의 이전 버전이 허용되더라도 계열 별칭이 최신 버전만을 기준으로 대체되거나 거부되었습니다.
2720 2771
2721**해결 방법:**2772**해결 방법:**
2722 2773
2723* `/model`을 실행하여 조직이 허용하는 모델 중에서 선택합니다. 제한된 모델은 선택기에 표시되지 않습니다.2774* `/model`을 실행하여 조직이 허용하는 모델 중에서 선택하십시오. 제한된 모델은 선택기에서 숨겨집니다.
2724* 제한된 모델이 `--model`, `ANTHROPIC_MODEL`, 설정 파일의 `model` 필드, 또는 [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md#choose-a-model), 스킬, 명령의 `model` frontmatter에 설정되어 있다면, 알림이 반복되지 않도록 해당 값을 제거하거나 업데이트하십시오2775* 제한된 모델이 `--model`, `ANTHROPIC_MODEL`, 설정 파일의 `model` 필드, 또는 [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md#choose-a-model), 스킬, 명령의 `model` frontmatter에 설정되어 있다면 알림이 재발하지 않도록 해당 값을 제거하거나 업데이트하십시오
2725* 제한된 모델에 액세스해야 한다면 조직 관리자에게 활성화를 요청하십시오. [조직 모델 제한](https://code.claude.com/docs/ko/model-config.md#organization-model-restrictions)을 참조하십시오.2776* 제한된 모델에 접근해야 한다면 조직 관리자에게 활성화를 요청하십시오. [조직 모델 제한](https://code.claude.com/docs/ko/model-config.md#organization-model-restrictions)을 참조하십시오.
2726 2777
2727### Can't switch to the default model2778### Can't switch to the default model
2728 2779
2732Can'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".2783Can'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".
2733```2784```
2734 2785
2735콜론 뒤의 문구는 전환을 차단한 원인을 나타냅니다.2786콜론 뒤의 문구는 무엇이 전환을 막았는지 알려 줍니다.
2736 2787
2737* **`your organization's managed settings block it ... in "deniedModels"`**: 관리형 거부 목록이 Default 옵션이 해석되는 모델을 차단합니다2788* **`your organization's managed settings block it ... in "deniedModels"`**: 관리형 거부 목록이 Default 옵션이 해석되는 모델을 차단합니다
2738* **`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 옵션이 해석되는 모델이 없습니다2789* **`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 옵션이 해석되는 모델이 포함되어 있지 않습니다
2739* **`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가 확인 없이 전환을 적용하는 대신 거부했습니다2790* **`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는 확인 없이 전환을 적용하는 대신 전환을 거부합니다
2740 2791
2741**해결 방법:**2792**해결 방법:**
2742 2793
2743* [`deniedModels`](https://code.claude.com/docs/ko/settings-reference#deniedmodels) 및 `availableModels` 문구의 경우 `/model`을 실행하고 조직이 허용하는 모델을 이름으로 선택합니다2794* [`deniedModels`](https://code.claude.com/docs/ko/settings-reference#deniedmodels) 및 `availableModels` 문구의 경우, `/model`을 실행하고 조직이 허용하는 모델을 이름으로 선택하십시오
2744* 관리자에게 메시지가 명시하는 관리형 설정을 업데이트해 달라고 요청합니다2795* 관리자에게 메시지에 표시된 관리형 설정을 업데이트해 달라고 요청하십시오
2745* `couldn't read` 문구의 경우 Claude Code를 재시작합니다. 계속 발생하면 관리자에게 관리형 설정을 확인해 달라고 요청하십시오2796* `couldn't read` 문구의 경우 Claude Code를 재시작하십시오. 계속 발생한다면 관리자에게 관리형 설정을 확인해 달라고 요청하십시오
2746 2797
2747이러한 관리형 설정에서 세션이 대신 `Claude Code can't start` 메시지와 함께 시작되지 않는 경우 [관리형 설정이 기본 모델을 차단하는 경우](#managed-settings-block-the-default-model)를 참조하십시오.2798대신 이러한 관리형 설정에서 `Claude Code can't start` 메시지와 함께 세션 시작이 실패한다면 [Managed settings block the default model](#managed-settings-block-the-default-model)을 참조하십시오.
2748 2799
2749### Model switch was blocked by a PreModelSwitch hook2800### Model switch was blocked by a PreModelSwitch hook
2750 2801
2751[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`으로 표시됩니다.2802[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`으로 표시됩니다.
2752 2803
2753```text theme={null}2804```text theme={null}
2754Model switch to Opus 4.6 was blocked by a PreModelSwitch hook: Opus 4.6 is retired for this project. Use a newer model.2805Model switch to Opus 4.6 was blocked by a PreModelSwitch hook: Opus 4.6 is retired for this project. Use a newer model.
2755```2806```
2756 2807
2757콜론 뒤의 이유는 무엇이 전환을 거부했는지를 나타냅니다.2808콜론 뒤의 이유는 무엇이 전환을 거부했는지 알려 줍니다.
2758 2809
2759* **훅이 작성한 이유**: PreModelSwitch 훅이 [전환을 거부하거나 확인을 요청](https://code.claude.com/docs/ko/hooks.md#premodelswitch-decision-control)할 때 해당 이유를 제공했습니다. 요청 사항을 해결하거나 훅이 허용하는 모델을 선택하십시오.2810* **훅이 작성한 이유**: PreModelSwitch 훅이 [전환을 거부하거나 확인을 요청](https://code.claude.com/docs/ko/hooks.md#premodelswitch-decision-control)할 때 해당 이유를 제공했습니다. 요청 사항을 해결하거나, 훅이 허용하는 모델을 선택하십시오.
2760* **`PreModelSwitch hook <name> did not respond before its timeout`**: [타임아웃](https://code.claude.com/docs/ko/hooks.md#timeouts) 전에 응답하지 않는 훅은 전환을 차단합니다. 멈춘 명령을 수정하거나 해당 훅의 `timeout`을 늘린 후 다시 전환하십시오.2811* **`PreModelSwitch hook <name> did not respond before its timeout`**: [타임아웃](https://code.claude.com/docs/ko/hooks.md#timeouts) 전에 응답하지 않는 훅은 전환을 차단합니다. 멈춘 명령을 수정하거나 해당 훅의 `timeout`을 늘린 후 다시 전환하십시오.
2761* **`confirmation required, and this session cannot ask`**: 훅이 이유 없이 `ask`로 응답했으며, 제어 요청에는 확인 프롬프트를 표시할 방법이 없습니다. [`-p` 실행](https://code.claude.com/docs/ko/headless)의 `/model` 명령은 이유 뒤에 `(run /model interactively to confirm)`을 붙여 같은 상황을 보고합니다. 대화형 세션에서 전환하거나, 이 모델에 대한 훅의 결정을 변경하십시오.2812* **`confirmation required, and this session cannot ask`**: 훅이 이유 없이 `ask`로 응답했으며, 제어 요청에는 확인 프롬프트를 표시할 방법이 없습니다. [`-p` 실행](https://code.claude.com/docs/ko/headless)에서 `/model` 명령은 이유 뒤에 `(run /model interactively to confirm)`을 붙여 같은 상태를 보고합니다. 대화형 세션에서 전환하거나, 이 모델에 대한 훅의 결정을 변경하십시오.
2762* **`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`를 실행하고 다시 전환하여 세부 정보를 확인한 후, 플러그인을 수정하거나 관리자에게 수정을 요청하십시오.2813* **`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`를 실행하고 다시 전환하여 세부 정보를 캡처한 후, 플러그인을 수정하거나 관리자에게 수정을 요청하십시오.
2763* **`a PreModelSwitch hook failed before answering`** 또는 **`PreModelSwitch hooks were cancelled (the control stream closed) before answering`**: 훅 실행이 판정 없이 종료되었으며, Claude Code는 이를 승인으로 처리하지 않습니다. `claude --debug`를 실행하여 무엇이 실패했는지 확인한 후 다시 전환하십시오.2814* **`a PreModelSwitch hook failed before answering`** 또는 **`PreModelSwitch hooks were cancelled (the control stream closed) before answering`**: 훅 실행이 판정 없이 종료되었으며, Claude Code는 이를 승인으로 처리하지 않습니다. `claude --debug`를 실행하여 무엇이 실패했는지 확인한 후 다시 전환하십시오.
2764 2815
2765v2.1.260 이전에는 관리형 플러그인 거부 메시지가 `plugin hooks could not be loaded, so PreModelSwitch hooks could not be checked; see the debug log`였습니다. Claude Code는 플러그인 로드를 한 번 재시도한 후, 조직이 관리하는 플러그인이 없는 경우에도 세션의 이후 전환을 거부했습니다. 해당 버전에서는 세션을 재시작하여 플러그인 로드를 다시 실행하십시오.2816v2.1.260 이전에는 관리형 플러그인 거부 메시지가 `plugin hooks could not be loaded, so PreModelSwitch hooks could not be checked; see the debug log`였습니다. Claude Code는 플러그인 로드를 한 번 재시도한 후, 조직이 관리하는 플러그인이 없더라도 세션에서 이후의 전환을 거부했습니다. 해당 버전에서는 세션을 재시작하여 플러그인 로드를 다시 실행하십시오.
2766 2817
2767### Couldn't save it as your default2818### Couldn't save it as your default
2768 2819
2769`/model <name>` 또는 `/model` 선택기에서 `Enter`를 누르는 등의 방법으로 기본값으로 저장할 모델을 선택했지만, Claude Code가 사용자 설정 파일인 `~/.claude/settings.json`에 선택 내용을 기록할 수 없었습니다. 전환 자체는 적용되었으므로 현재 세션은 선택한 모델로 실행되지만, 기본값은 변경되지 않았으며 다음 세션은 이전 값으로 시작됩니다.2820`/model <name>`이나 `/model` 선택기의 `Enter` 등으로 기본값으로 저장할 모델을 선택했지만, Claude Code가 선택 내용을 사용자 설정 파일 `~/.claude/settings.json`에 기록하지 못했습니다. 전환 자체는 적용되었으므로 현재 세션은 선택한 모델로 실행되지만, 기본값은 변경되지 않았으며 다음 세션은 이전 값으로 시작됩니다.
2770 2821
2771```text theme={null}2822```text theme={null}
2772Set model to Fable 5.1 for this session only · couldn't save it as your default: ~/.claude/settings.json can't be written (EROFS)2823Set model to Fable 5.1 for this session only · couldn't save it as your default: ~/.claude/settings.json can't be written (EROFS)
2773```2824```
2774 2825
2775파일 경로 뒤의 이유는 무엇이 실패했는지를 나타냅니다.2826파일 경로 뒤의 이유는 무엇이 실패했는지 알려 줍니다.
2776 2827
2777* **`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)를 참조하십시오.2828* **`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)를 참조하십시오.
2778* **`isn't valid JSON`**: 디스크의 파일을 파싱할 수 없으며, Claude Code는 다시 읽을 수 없는 내용을 덮어쓰지 않고 그대로 둡니다. 구문 오류를 수정한 후 다시 전환하십시오. [손상된 설정 파일 수정](https://code.claude.com/docs/ko/settings.md#fix-a-broken-settings-file)을 참조하십시오.2829* **`isn't valid JSON`**: 디스크의 파일을 파싱할 수 없으며, Claude Code는 다시 읽을 수 없는 내용을 덮어쓰는 대신 파일을 그대로 둡니다. 구문 오류를 수정한 후 다시 전환하십시오. [손상된 설정 파일 수정](https://code.claude.com/docs/ko/settings.md#fix-a-broken-settings-file)을 참조하십시오.
2779 2830
2780`couldn't confirm it was saved as your default (~/.claude/settings.json is still being written)`로 끝나는 알림은 3초가 지나도 기록이 완료되지 않았다는 뜻입니다. 기록은 백그라운드에서 계속되므로 기본값이 여전히 저장될 수 있습니다. 다음 세션이 어떤 모델로 시작되는지 확인하거나 `/model <name>`을 다시 실행하십시오.2831`couldn't confirm it was saved as your default (~/.claude/settings.json is still being written)`로 끝나는 알림은 3초가 지나도 쓰기가 완료되지 않았다는 의미입니다. 쓰기는 백그라운드에서 계속되므로 기본값이 여전히 저장될 수 있습니다. 다음 세션이 어떤 모델로 시작되는지 확인하거나, `/model <name>`을 다시 실행하십시오.
2781 2832
2782v2.1.265 이전에는 기록이 실패한 경우에도 알림에 모델이 `saved as your default for new sessions`라고 표시되었습니다.2833v2.1.265 이전에는 쓰기가 실패한 경우에도 알림에 모델이 `saved as your default for new sessions`라고 표시되었습니다.
2783 2834
2784### Advisor is less capable than the current main model2835### Advisor is less capable than the current main model
2785 2836
2786[advisor 모델](https://code.claude.com/docs/ko/advisor.md)의 순위가 세션의 메인 모델보다 낮으므로, Claude Code는 선택 내용을 유지하지만 advisor를 메인 모델의 요청에 연결하지 않습니다.2837[advisor 모델](https://code.claude.com/docs/ko/advisor.md)의 순위가 세션의 메인 모델보다 낮으므로, Claude Code는 선택을 유지하지만 메인 모델의 요청에 advisor를 연결하지 않습니다.
2787 2838
2788```text theme={null}2839```text theme={null}
2789Advisor set to Opus 4.82840Advisor set to Opus 4.8
2790Note: 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.2841Note: 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.
2791```2842```
2792 2843
2793다른 메시지도 같은 상황을 보고합니다.2844다른 메시지도 같은 상태를 보고합니다.
2794 2845
2795* 대화형 세션에서는 `Advisor will not activate on the main model (advisor is less capable); subagents may still use it and may use more tokens · /advisor`라는 알림이 표시됩니다.2846* 대화형 세션에서는 `Advisor will not activate on the main model (advisor is less capable); subagents may still use it and may use more tokens · /advisor`라는 알림이 표시됩니다.
2796* [비대화형 모드](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)에만 기록합니다.2847* [비대화형 모드](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)에만 기록합니다.
2797 2848
2798**해결 방법:**2849**해결 방법:**
2799 2850
2800* 순위가 더 높은 advisor나 순위가 더 낮은 메인 모델을 선택합니다. [advisor 모델 선택](https://code.claude.com/docs/ko/advisor.md#choose-an-advisor-model)에서 순위를 확인하고 각 메인 모델에 허용되는 advisor 목록을 볼 수 있습니다.2851* 순위가 더 높은 advisor나 순위가 더 낮은 메인 모델을 선택하십시오. [advisor 모델 선택](https://code.claude.com/docs/ko/advisor.md#choose-an-advisor-model)에서 순위를 확인하고 각 메인 모델에 허용되는 advisor 목록을 볼 수 있습니다.
2801* advisor가 자문할 수 있는 모델의 [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md)가 계속 advisor를 사용하도록 하려면 advisor 설정을 그대로 두십시오2852* advisor가 자문할 수 있는 모델을 사용하는 [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md)가 계속 advisor를 사용하게 하려면 advisor를 설정된 상태로 두십시오
2802 2853
2803v2.1.287 이전에는 Claude Code가 여러 조합의 순위를 다르게 매겼습니다. Opus 4.7 또는 Opus 4.8 메인 모델과 Sonnet 5.5 advisor 조합에 대해 이 안내를 표시했지만, 현재는 이 조합을 허용합니다. 또한 Sonnet 5.5 메인 모델과 Opus 4.8 advisor처럼 현재는 이 안내를 표시하는 일부 advisor를 연결했습니다.2854v2.1.287 이전에는 Claude Code가 여러 조합의 순위를 다르게 매겼습니다. Opus 4.7 또는 Opus 4.8 메인 모델에 Sonnet 5.5 advisor를 조합한 경우 이 안내를 표시했지만, 이제는 이 조합을 허용합니다. 또한 Sonnet 5.5 메인 모델에 Opus 4.8 advisor를 조합한 경우처럼, 현재는 이 안내가 표시되는 일부 advisor를 연결했습니다.
2804 2855
2805### thinking.type.enabled is not supported for this model2856### thinking.type.enabled is not supported for this model
2806 2857
2807Claude Code 버전이 선택한 모델에 필요한 최소 버전보다 오래되었습니다. CLI가 모델이 더 이상 허용하지 않는 사고 구성을 보냈습니다.2858Claude Code 버전이 선택한 모델의 최소 버전보다 오래되었습니다. CLI가 모델이 더 이상 허용하지 않는 사고 구성을 보냈습니다.
2808 2859
2809```text theme={null}2860```text theme={null}
2810API Error: 400 ... "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.2861API Error: 400 ... "thinking.type.enabled" is not supported for this model. Use "thinking.type.adaptive" and "output_config.effort" to control thinking behavior.
2812 2863
2813**해결 방법:**2864**해결 방법:**
2814 2865
2815* `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 이상이 필요합니다2866* `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 이상이 필요합니다
2816* [stable 릴리스 채널](https://code.claude.com/docs/ko/setup.md#configure-release-channel)에서는 업데이트해도 최신 stable 릴리스보다 더 새로운 버전으로 이동하지 않으며, 이 릴리스도 위 버전보다 오래되었을 수 있습니다. latest 채널로 이동한 후 업데이트하십시오2867* [stable 릴리스 채널](https://code.claude.com/docs/ko/setup.md#configure-release-channel)에서는 업데이트해도 최신 stable 릴리스보다 높은 버전으로 이동하지 않으며, 이 릴리스가 여전히 위 버전보다 오래되었을 수 있습니다. latest 채널로 이동한 후 업데이트하십시오
2817* 업그레이드할 수 없다면 `/model`을 실행하고 대신 Opus 4.6 또는 Sonnet 4.6을 선택합니다2868* 업그레이드할 수 없다면 `/model`을 실행하고 대신 Opus 4.6 또는 Sonnet 4.6을 선택하십시오
2818* [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 이상이 필요합니다2869* [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 이상이 필요합니다
2819 2870
2820### 사고가 꺼진 상태에서는 effort를 사용할 수 없음2871### Effort isn't available with thinking turned off
2821 2872
2822[확장 사고](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가 요청을 거부했습니다.2873[확장 사고](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가 요청을 거부했습니다.
2823 2874
2824```text theme={null}2875```text theme={null}
2825API 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)2876API 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)
2826```2877```
2827 2878
2828`·` 뒤의 힌트는 세션에 따라 다릅니다. 비대화형 세션에서는 `use --effort high (or the effortLevel setting)`으로, Claude Desktop 앱이 실행하는 세션에서는 `you can lower effort to High`로 표시됩니다.2879`·` 뒤의 힌트는 세션에 따라 다릅니다. 비대화형 세션에서는 `use --effort high (or the effortLevel setting)`로, Claude Desktop 앱이 실행하는 세션에서는 `you can lower effort to High`로 표시됩니다.
2829 2880
2830**해결 방법:**2881**해결 방법:**
2831 2882
2832* [effort 수준을](https://code.claude.com/docs/ko/model-config.md#set-the-effort-level) `high` 이하로 낮춥니다.2883* [effort 수준을 낮추어](https://code.claude.com/docs/ko/model-config.md#set-the-effort-level) `high` 이하로 설정하십시오.
2833* 예를 들어 [`MAX_THINKING_TOKENS`](https://code.claude.com/docs/ko/env-vars) 설정을 해제하거나 설정에서 [`"alwaysThinkingEnabled": false`](https://code.claude.com/docs/ko/settings-reference#alwaysthinkingenabled)를 제거하여 사고를 다시 켭니다.2884* 예를 들어 [`MAX_THINKING_TOKENS`](https://code.claude.com/docs/ko/env-vars) 설정을 해제하거나 설정에서 [`"alwaysThinkingEnabled": false`](https://code.claude.com/docs/ko/settings-reference#alwaysthinkingenabled)를 제거하여 사고를 다시 켜십시오.
2834 2885
2835v2.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`로 요청을 보냅니다.2886v2.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`로 요청을 보냅니다.
2836 2887
2837### Thinking budget exceeds output limit2888### 사고 예산이 출력 한도를 초과함
2838 2889
2839구성된 확장 사고 예산이 최대 응답 길이를 초과하여 실제 답변을 위한 공간이 남아 있지 않습니다.2890구성된 확장 사고 예산이 최대 응답 길이를 초과하여 실제 답변을 위한 공간이 남지 않았습니다.
2840 2891
2841```text theme={null}2892```text theme={null}
2842API Error: 400 ... max_tokens must be greater than thinking.budget_tokens2893API Error: 400 ... max_tokens must be greater than thinking.budget_tokens
2844 2895
2845**해결 방법:**2896**해결 방법:**
2846 2897
2847* [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](https://code.claude.com/docs/ko/env-vars)를 사고 예산보다 높게 올립니다2898* [`CLAUDE_CODE_MAX_OUTPUT_TOKENS`](https://code.claude.com/docs/ko/env-vars)를 사고 예산보다 높게 설정하십시오
2848* 예산이 출력 길이와 어떻게 상호 작용하는지는 [확장 사고](https://code.claude.com/docs/ko/model-config.md#extended-thinking)를 참조하십시오2899* 예산이 출력 길이와 어떻게 상호작용하는지는 [확장 사고](https://code.claude.com/docs/ko/model-config.md#extended-thinking)를 참조하십시오
2849 2900
2850### Response exceeded the output token maximum2901### Response exceeded the output token maximum
2851 2902
2852Claude의 응답이 요청에서 허용한 최대 출력 토큰 수에 도달하여 그 지점에서 잘렸습니다.2903Claude의 응답이 요청에서 허용하는 최대 출력 토큰 수에 도달하여 그 지점에서 잘렸습니다.
2853 2904
2854```text theme={null}2905```text theme={null}
2855API Error: Claude's response exceeded the ... output token maximum. To configure this behavior, set the CLAUDE_CODE_MAX_OUTPUT_TOKENS environment variable.2906API Error: Claude's response exceeded the ... output token maximum. To configure this behavior, set the CLAUDE_CODE_MAX_OUTPUT_TOKENS environment variable.
2856API 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.2907API 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.
2857```2908```
2858 2909
2859`a request sent without streaming`을 명시하는 형태는 스트리밍 요청이 실패하여 Claude Code가 스트리밍 없이 다시 보냈다는 뜻이며, 이 경우 응답은 64,000 출력 토큰으로 제한됩니다. v2.1.299 이전에는 이렇게 다시 보낸 요청에서 잘린 응답이 이 메시지 없이 응답이 완료된 것처럼 턴을 종료했습니다.2910`a request sent without streaming`이 표시된 형식은 스트리밍 요청이 실패하여 Claude Code가 스트리밍 없이 다시 보냈다는 의미이며, 이 경우 응답이 64,000 출력 토큰으로 제한됩니다. v2.1.299 이전에는 이렇게 다시 보낸 요청에서 응답이 잘리면, 이 메시지 없이 응답이 완료된 것처럼 턴이 종료되었습니다.
2860 2911
2861**해결 방법:**2912**해결 방법:**
2862 2913
2863* 응답이 잘리기 전에 Claude가 일부 텍스트를 작성했다면, 대화형 세션에서 `continue`로 답하여 나머지를 요청합니다. 그 텍스트는 대화에 남아 있습니다.2914* 응답이 잘리기 전에 Claude가 일부 텍스트를 작성했다면, 대화형 세션에서 `continue`로 답하여 나머지를 요청하십시오. 해당 텍스트는 대화에 남아 있습니다.
2864* 메시지가 `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)을 참조하십시오2915* 메시지에서 `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)을 참조하십시오
2865* 각 응답이 한도를 넘지 않도록 하려면, 응답당 파일 하나나 섹션 하나처럼 Claude에게 출력을 더 작은 단위로 요청하십시오2916* 각 응답이 한도를 넘지 않도록, 응답마다 파일 하나 또는 섹션 하나처럼 더 작은 단위로 출력을 요청하십시오
2866 2917
2867### Tool use or thinking block mismatch2918### 도구 사용 또는 thinking 블록 불일치
2868 2919
2869대화 기록이 일관되지 않은 상태로 API에 도달했습니다.2920대화 기록이 일관되지 않은 상태로 API에 전달되었습니다.
2870 2921
2871```text theme={null}2922```text theme={null}
2872API Error: 400 due to tool use concurrency issues. Run /rewind to recover the conversation.2923API Error: 400 due to tool use concurrency issues. Run /rewind to recover the conversation.
2880 2931
2881**해결 방법:**2932**해결 방법:**
2882 2933
2883* Opus 4.7 또는 Opus 4.8을 사용 중이라면 먼저 `claude update`를 실행하십시오. v2.1.156 이전 버전은 일반적인 도구 사용 중에도 이 오류를 일으킬 수 있으며, `/rewind`로 해결되지 않습니다.2934* Opus 4.7 또는 Opus 4.8을 사용 중이라면 먼저 `claude update`를 실행하십시오. v2.1.156 이전 버전은 일반적인 도구 사용 중에 이 오류를 일으킬 수 있으며, `/rewind`로는 해결되지 않습니다.
2884* `/rewind`를 실행하거나 Esc를 두 번 눌러 손상된 턴 이전의 체크포인트로 되돌아간 후 그 지점부터 계속합니다. 체크포인트가 생성되고 복원되는 방식은 [체크포인트](https://code.claude.com/docs/ko/checkpointing.md)를 참조하십시오.2935* `/rewind`를 실행하거나 Esc를 두 번 눌러 손상된 턴 이전의 체크포인트로 되돌아간 후 그곳에서 계속하십시오. 체크포인트가 생성되고 복원되는 방식은 [체크포인트](https://code.claude.com/docs/ko/checkpointing.md)를 참조하십시오.
2885 2936
2886### Invalid data in redacted\_thinking block2937### Invalid data in redacted\_thinking block
2887 2938
2888대화 기록의 이전 턴에 포함된 `redacted_thinking` 블록을 API가 수락할 수 없어서 400으로 요청을 거부했습니다.2939대화 기록의 이전 턴에 포함된 `redacted_thinking` 블록을 허용할 수 없었기 때문에 API가 400으로 요청을 거부했습니다.
2889 2940
2890```text theme={null}2941```text theme={null}
2891API Error: 400 ... Invalid `data` in `redacted_thinking` block2942API Error: 400 ... Invalid `data` in `redacted_thinking` block
2892```2943```
2893 2944
2894Claude Code는 대화의 이전 사고를 요청에서 제외하고 한 번 재시도하므로, 세션은 오류를 표시하지 않고 계속됩니다. v2.1.282 이전에는 Claude Code가 거부된 블록을 유지했기 때문에 이후 모든 턴이 같은 오류로 실패했습니다.2945Claude Code는 대화의 이전 사고를 요청에서 제외하고 한 번 재시도하므로, 세션은 오류를 표시하지 않고 계속됩니다. v2.1.282 이전에는 Claude Code가 거부된 블록을 유지했기 때문에 이후의 모든 턴이 같은 오류로 실패했습니다.
2895 2946
2896**해결 방법:**2947**해결 방법:**
2897 2948
2898* v2.1.281 이하 버전에서 모든 턴이 이 오류로 실패한다면 `claude update`를 실행하고 세션을 재개합니다2949* v2.1.281 이하 버전을 사용 중이고 모든 턴이 이 오류로 실패한다면 `claude update`를 실행하고 세션을 재개하십시오
2899* 오류가 계속되면 `/clear`를 실행하여 해당 블록이 없는 대화를 시작합니다2950* 오류가 지속되면 `/clear`를 실행하여 해당 블록이 포함되지 않은 대화를 시작하십시오
2900 2951
2901### Unsupported tool content removed2952### Unsupported tool content removed
2902 2953
2903Claude Code가 Anthropic API에 직접 연결하여 저장된 세션을 로드하거나 미리 볼 때, Anthropic API가 허용하지 않는 도구 내용을 제거하고, 제거된 내용이 두 thinking 블록 사이에 있던 위치에 다음 줄을 남깁니다.2954Claude Code가 Anthropic API에 직접 연결하여 저장된 세션을 로드하거나 미리 볼 때, Anthropic API가 허용하지 않는 도구 콘텐츠를 제거하고, 제거된 콘텐츠가 두 thinking 블록 사이에 있던 위치에 다음 줄을 남깁니다.
2904 2955
2905```text theme={null}2956```text theme={null}
2906[Unsupported tool content removed]2957[Unsupported tool content removed]
2907```2958```
2908 2959
2909이러한 내용은 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 오류로 실패했습니다.2960이러한 콘텐츠는 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 오류로 실패했습니다.
2910 2961
2911**해결 방법:**2962**해결 방법:**
2912 2963
2913* 자리 표시자 줄이 보이면 별도 조치가 필요하지 않습니다. 세션은 제거된 내용 없이 계속됩니다.2964* 자리 표시 줄이 보이는 경우에는 조치가 필요하지 않습니다. 세션은 제거된 콘텐츠 없이 계속됩니다.
2914* 대신 재개된 세션의 모든 턴이 400 오류로 실패한다면 `claude update`를 실행하고 세션을 다시 재개하십시오. v2.1.246 이전 버전은 해당 내용을 제거하지 않습니다.2965* 대신 재개된 세션의 모든 턴이 400 오류로 실패한다면 `claude update`를 실행하고 세션을 다시 재개하십시오. v2.1.246 이전 버전은 해당 콘텐츠를 제거하지 않습니다.
2915 2966
2916### role 'system' must precede an 'assistant' message2967### role 'system' must precede an 'assistant' message
2917 2968
2918시스템 메시지가 대화에서 API가 허용하지 않는 위치에 있기 때문에 API가 400으로 요청을 거부했습니다.2969대화에서 허용되지 않는 위치에 시스템 메시지가 있기 때문에 API가 400으로 요청을 거부했습니다.
2919 2970
2920```text theme={null}2971```text theme={null}
2921API Error: 400 messages.6: role 'system' must precede an 'assistant' message or end the array; ...2972API Error: 400 messages.6: role 'system' must precede an 'assistant' message or end the array; ...
2922```2973```
2923 2974
2924Claude Code는 일부 리마인더 및 첨부 텍스트를 대화 내의 시스템 메시지로 보냅니다. API가 그 위치를 거부하면, Claude Code는 해당 텍스트를 일반 사용자 메시지로 보내는 방식으로 요청을 한 번 재시도합니다. `use the top-level 'system' parameter for the initial system prompt` 같은 API의 유사한 위치 관련 문구도 같은 방식으로 복구됩니다.2975Claude Code는 리마인더와 첨부 파일 텍스트 중 일부를 대화 내의 시스템 메시지로 보냅니다. API가 그 위치를 거부하면, Claude Code는 해당 텍스트를 일반 사용자 메시지로 보내는 방식으로 요청을 한 번 재시도합니다. `use the top-level 'system' parameter for the initial system prompt`처럼 API의 유사한 위치 관련 문구에도 같은 복구가 적용됩니다.
2925 2976
2926오류가 실제로 표시된다면, 거부된 시스템 메시지는 Claude Code가 제거할 수 있는 것이 아닙니다. 이는 보통 Claude Code와 API 사이의 프록시나 [LLM 게이트웨이](https://code.claude.com/docs/ko/llm-gateway)가 자체 시스템 메시지를 추가했다는 뜻입니다.2977오류가 나타난다면 거부된 시스템 메시지는 Claude Code가 제거할 수 있는 것이 아닙니다. 이는 대개 Claude Code와 API 사이의 프록시나 [LLM 게이트웨이](https://code.claude.com/docs/ko/llm-gateway)가 자체 시스템 메시지를 추가했다는 의미입니다.
2927 2978
2928**해결 방법:**2979**해결 방법:**
2929 2980
2930* [`ANTHROPIC_BASE_URL`](https://code.claude.com/docs/ko/env-vars)로 구성된 프록시나 게이트웨이 뒤에서 오류가 매 턴마다 반복된다면, 프록시 없이 연결하여 원인을 확인하고 해당 프록시 운영자에게 오류를 보고하십시오2981* [`ANTHROPIC_BASE_URL`](https://code.claude.com/docs/ko/env-vars)로 구성된 프록시나 게이트웨이 뒤에서 매 턴마다 오류가 반복된다면, 프록시 없이 연결하여 원인을 확인하고 운영자에게 오류를 보고하십시오
2931* `/clear`를 실행하여 새 대화를 시작합니다. 거기서도 오류가 다시 발생한다면, 원인은 저장된 대화가 아니라 요청 경로에 있습니다.2982* `/clear`를 실행하여 새 대화를 시작하십시오. 그곳에서도 오류가 다시 발생한다면 원인은 저장된 대화가 아니라 요청 경로에 있습니다.
2932 2983
2933v2.1.280 이전에는 Claude Code가 이 문구를 인식하지 못했기 때문에, 거부된 시스템 메시지가 Claude Code 자신이 보낸 것일 때도 오류가 표시되었고 대화의 이후 모든 턴이 같은 방식으로 실패했습니다.2984v2.1.280 이전에는 Claude Code가 이 문구를 인식하지 못했기 때문에, 거부된 시스템 메시지가 Claude Code 자체가 보낸 것인 경우에도 오류가 나타났고 대화의 이후 모든 턴이 같은 방식으로 실패했습니다.
2934 2985
2935### Invalid encrypted\_content in search\_result block2986### Invalid encrypted\_content in search\_result block
2936 2987
2937대화 기록에 API가 복호화할 수 없는 호스팅 웹 검색 내용이 포함되어 있어 API가 400으로 요청을 거부했습니다. 문구에는 읽을 수 없는 필드가 명시됩니다.2988대화 기록에 API가 복호화할 수 없는 호스팅 웹 검색 콘텐츠가 포함되어 있어 API가 400으로 요청을 거부했습니다. 문구에는 읽을 수 없는 필드가 표시됩니다.
2938 2989
2939```text theme={null}2990```text theme={null}
2940API Error: 400 ... Invalid `encrypted_content` in `search_result` block2991API Error: 400 ... Invalid `encrypted_content` in `search_result` block
2943API Error: 400 ... Invalid `encrypted_stdout` in `encrypted_code_execution_result` block2994API Error: 400 ... Invalid `encrypted_stdout` in `encrypted_code_execution_result` block
2944```2995```
2945 2996
2946API의 호스팅 [웹 검색 도구](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool) 결과에는 API만 읽을 수 있는 암호화된 필드가 포함됩니다. `encrypted_stdout` 문구는 이러한 결과를 읽은 호스팅 코드 실행 프로그램의 출력을 가리키며, API는 이 출력도 암호화합니다. API는 다른 조직을 위해 생성된 내용처럼 복호화할 수 없는 내용을 다시 보내는 요청을 거부합니다.2997API의 호스팅 [웹 검색 도구](https://platform.claude.com/docs/en/agents-and-tools/tool-use/web-search-tool)의 결과에는 API만 읽을 수 있는 암호화된 필드가 포함됩니다. `encrypted_stdout` 문구는 이러한 결과를 읽은 호스팅 코드 실행 프로그램의 출력을 가리키며, API는 이 출력도 암호화합니다. API는 다른 조직을 위해 생성된 콘텐츠처럼 복호화할 수 없는 콘텐츠를 다시 보내는 요청을 거부합니다.
2947 2998
2948Claude Code 자체의 [WebSearch 도구](https://code.claude.com/docs/ko/tools-reference.md#websearch-tool-behavior)는 검색 결과를 일반 텍스트로 기록하므로, 이러한 블록은 보통 호스팅 웹 검색을 직접 실행한 프록시나 [LLM 게이트웨이](https://code.claude.com/docs/ko/llm-gateway)를 통해 대화에 들어옵니다.2999Claude Code 자체의 [WebSearch 도구](https://code.claude.com/docs/ko/tools-reference.md#websearch-tool-behavior)는 검색 결과를 일반 텍스트로 기록하므로, 이러한 블록은 대개 호스팅 웹 검색을 자체적으로 실행한 프록시나 [LLM 게이트웨이](https://code.claude.com/docs/ko/llm-gateway)를 통해 대화에 들어옵니다.
2949 3000
2950세 가지 웹 검색 문구의 경우, Claude Code는 검색 호출, 결과, 인용을 전송 내용에서 제외하고 요청을 한 번 재시도하므로, 세션은 오류를 표시하지 않고 계속됩니다. `encrypted_stdout` 문구에는 이러한 복구가 없으므로 해당 메시지는 여전히 표시됩니다. v2.1.282 이전에는 Claude Code가 거부된 웹 검색 블록도 유지했기 때문에, 이후 모든 턴과 `/compact`가 같은 방식으로 실패했습니다.3001세 가지 웹 검색 문구의 경우, Claude Code는 검색 호출, 결과, 인용을 보내는 내용에서 제외하고 요청을 한 번 재시도하므로, 세션은 오류를 표시하지 않고 계속됩니다. `encrypted_stdout` 문구에는 이런 복구가 없으므로 해당 메시지는 여전히 표시됩니다. v2.1.282 이전에는 Claude Code가 거부된 웹 검색 블록도 유지했기 때문에, 이후의 모든 턴과 `/compact`가 같은 방식으로 실패했습니다.
2951 3002
2952**해결 방법:**3003**해결 방법:**
2953 3004
2954* v2.1.281 이하 버전에서 모든 턴이 웹 검색 문구 중 하나로 실패한다면 `claude update`를 실행하고 세션을 재개합니다3005* v2.1.281 이하 버전을 사용 중이고 모든 턴이 웹 검색 문구 중 하나로 실패한다면 `claude update`를 실행하고 세션을 재개하십시오
2955* 오류가 계속되거나 메시지에 `encrypted_stdout`이 명시된 경우, `/rewind`를 실행하여 해당 내용을 추가한 턴 이전의 체크포인트로 되돌아가거나, `/clear`를 실행하여 해당 내용이 없는 대화를 시작합니다3006* 오류가 지속되거나 메시지에 `encrypted_stdout`이 표시된다면, `/rewind`를 실행하여 해당 콘텐츠를 추가한 턴 이전의 체크포인트로 되돌아가거나, `/clear`를 실행하여 해당 콘텐츠가 포함되지 않은 대화를 시작하십시오
2956* 프록시나 게이트웨이 뒤에서 Claude Code를 실행한다면 해당 운영자에게 오류를 보고하십시오3007* 프록시나 게이트웨이 뒤에서 Claude Code를 실행한다면 운영자에게 오류를 보고하십시오
2957 3008
2958### Usage Policy refusal3009### Usage Policy refusal
2959 3010
2960대화의 내용이 [이용 정책](https://www.anthropic.com/legal/aup) 검사를 트리거하여 API가 응답을 거절했습니다.3011대화의 콘텐츠가 [사용 정책](https://www.anthropic.com/legal/aup) 검사를 트리거하여 API가 응답을 거부했습니다.
2961 3012
2962메시지에 `` Details: `[reasoning_extraction]` `` 줄이 포함되어 있다면 [세이프가드가 Claude의 추론에 대한 요청을 감지한 경우](#safeguards-flagged-a-request-for-claudes-reasoning)를 참조하십시오.3013메시지에 `` Details: `[reasoning_extraction]` `` 줄이 포함되어 있다면 [Claude의 추론을 요청하는 요청이 세이프가드에 의해 플래그됨](#safeguards-flagged-a-request-for-claudes-reasoning)을 참조하십시오.
2963 3014
2964메시지에는 거절이 잘못되었다고 판단될 때 지원팀에 전달할 수 있는 Request ID와 Message ID가 포함됩니다.3015메시지에는 거부가 잘못되었다고 판단될 경우 지원팀에 전달할 수 있는 Request ID와 Message ID가 포함되어 있습니다.
2965 3016
2966```text theme={null}3017```text theme={null}
2967API Error: Opus 4.6 can't help with this. Start a new session to continue.3018API Error: Opus 4.6 can't help with this. Start a new session to continue.
2969Send feedback with /feedback or learn more: https://www.anthropic.com/legal/aup3020Send feedback with /feedback or learn more: https://www.anthropic.com/legal/aup
2970```3021```
2971 3022
2972메시지에는 거절한 모델의 이름이 표시되며, 기록된 모델이 없으면 `Claude`가 표시됩니다.3023메시지에는 거부한 모델의 이름이 표시되며, 기록된 모델이 없는 경우에는 `Claude`가 표시됩니다.
2973 3024
2974검사는 최신 프롬프트뿐만 아니라 대화 전체를 평가하므로, 같은 세션에서 새 메시지를 보내면 보통 같은 거절이 다시 트리거됩니다. 디스크의 트랜스크립트에 여전히 트리거한 내용이 남아 있으므로, 세션을 종료한 후 `--continue` 또는 `--resume`으로 다시 열어도 마찬가지입니다. [Amazon Bedrock](https://code.claude.com/docs/ko/amazon-bedrock.md), [Google Cloud's 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)를 참조하십시오.3025이 검사는 최신 프롬프트만이 아니라 전체 대화를 평가하므로, 같은 세션에서 새 메시지를 보내면 대개 동일한 거부가 다시 트리거됩니다. 세션을 종료한 후 `--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)을 참조하십시오.
2975 3026
2976v2.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.`였습니다.3027v2.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.`로 표시되었습니다.
2977 3028
2978**해결 방법:**3029**해결 방법:**
2979 3030
2980* Esc를 두 번 누르거나 `/rewind`를 실행하여 거절을 트리거한 턴 이전의 체크포인트로 되돌아간 후, 표현을 바꾸거나 다른 접근 방식을 사용합니다. [체크포인트](https://code.claude.com/docs/ko/checkpointing.md)를 참조하십시오.3031* Esc를 두 번 누르거나 `/rewind`를 실행하여 거부를 트리거한 턴 이전의 체크포인트로 되돌아간 다음, 표현을 바꾸거나 다른 접근 방식을 사용하십시오. [체크포인트](https://code.claude.com/docs/ko/checkpointing.md)를 참조하십시오.
2981* 어떤 턴이 원인인지 파악할 수 없다면 `/clear`를 실행하여 같은 프로젝트에서 새 대화를 시작합니다. 이전 대화는 디스크에 보존되며 `/resume`에서 계속 사용할 수 있습니다.3032* 어떤 턴이 원인인지 파악할 수 없다면 `/clear`를 실행하여 같은 프로젝트에서 새 대화를 시작하십시오. 이전 대화는 디스크에 보존되며 `/resume`에서 계속 사용할 수 있습니다.
2982* 되감기를 사용할 수 없는 [비대화형 모드](https://code.claude.com/docs/ko/headless.md)(`-p`)에서는 `--continue` 없이 새 세션에서 표현을 바꾼 프롬프트로 재시도하십시오. 정책 검사는 모델마다 다르므로, 경우에 따라 `--model`로 다른 모델로 전환하면 거절이 해결될 수도 있습니다.3033* 되감기를 사용할 수 없는 [비대화형 모드](https://code.claude.com/docs/ko/headless.md)(`-p`)에서는 `--continue` 없이 새 세션에서 표현을 바꾼 프롬프트로 재시도하십시오. 정책 검사는 모델마다 다르므로 `--model`로 다른 모델로 전환하면 경우에 따라 거부가 해결될 수도 있습니다.
2983 3034
2984### 안전 조치가 사이버 보안 주제로 플래그 지정함3035### Safety measures flagged a cybersecurity topic
2985 3036
2986모델의 안전 조치가 대화 내용을 사이버 보안 주제로 플래그 지정했습니다. 메시지에는 요청을 플래그 지정한 모델의 이름이 표시됩니다.3037모델의 안전 조치가 대화의 콘텐츠를 사이버 보안 주제로 플래그했습니다. 메시지에는 요청을 플래그한 모델의 이름이 표시됩니다.
2987 3038
2988```text theme={null}3039```text theme={null}
2989API 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-claude3040API 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
2990```3041```
2991 3042
2992메시지에 `` Details: `[reasoning_extraction]` `` 줄이 포함되어 있다면 [안전 장치가 Claude의 추론을 요청하는 것으로 플래그 지정함](#safeguards-flagged-a-request-for-claudes-reasoning)을 참조하세요.3043메시지에 `` Details: `[reasoning_extraction]` `` 줄이 포함되어 있다면 [Claude의 추론을 요청하는 요청이 세이프가드에 의해 플래그됨](#safeguards-flagged-a-request-for-claudes-reasoning)을 참조하십시오.
2993 3044
2994이 메시지는 정당한 사이버 보안 작업에 대한 액세스 권한을 부여하는 [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가 대신 모델을 전환하는 경우도 다룹니다.3045이 메시지는 정당한 사이버 보안 작업에 대한 액세스 권한을 부여하는 [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가 대신 모델을 전환하는 경우도 다룹니다.
2995 3046
2996[Amazon Bedrock](https://code.claude.com/docs/ko/amazon-bedrock.md), [Google Cloud's 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) 메시지가 표시됩니다.3047[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) 메시지가 표시됩니다.
2997 3048
2998**해결 방법:**3049**해결 방법:**
2999 3050
3000* 작업에 이 콘텐츠가 필요한 경우 [Cyber Verification Program](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)을 통해 액세스를 신청합니다3051* 작업에 이 콘텐츠가 필요한 경우 [Cyber Verification Program](https://support.claude.com/en/articles/14604842-real-time-cyber-safeguards-on-claude)을 통해 액세스를 신청하십시오
3001* 요청이 사이버 보안 주제와 관련이 없었다면 `/feedback`을 실행하여 오탐을 보고합니다3052* 요청이 사이버 보안 주제와 관련이 없었다면 `/feedback`을 실행하여 오탐을 보고하십시오
3002* 같은 세션에서 작업을 계속하려면 Esc를 두 번 누르거나 `/rewind`를 실행하여 플래그를 유발한 턴 이전의 체크포인트로 되돌아간 다음 다른 방식으로 접근합니다. [체크포인트](https://code.claude.com/docs/ko/checkpointing.md)를 참조하세요.3053* 같은 세션에서 작업을 계속하려면 Esc를 두 번 누르거나 `/rewind`를 실행하여 플래그를 트리거한 턴 이전의 체크포인트로 되돌아간 다음 다른 접근 방식을 사용하십시오. [체크포인트](https://code.claude.com/docs/ko/checkpointing.md)를 참조하십시오.
3003 3054
3004표시되는 메시지의 문구가 다음 중 하나와 같다면 이전 Claude Code 버전에서 표시되는 동일한 플래그입니다.3055표시된 메시지가 대신 다음 중 하나와 같은 문구라면, 이전 Claude Code 버전에서 발생한 동일한 플래그입니다.
3005 3056
3006* v2.1.219부터 v2.1.296까지는 메시지의 마지막 문장 앞에 `Apply to the Cyber Verification Program to reduce these interruptions.`가 포함될 수도 있었습니다3057* v2.1.219부터 v2.1.296까지는 메시지의 마지막 문장 앞에 `Apply to the Cyber Verification Program to reduce these interruptions.`가 포함될 수도 있었습니다
3007* 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.`가 이어졌습니다3058* 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.`가 이어서 표시되었습니다.
3008* 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:`였으며 그 뒤에 예외 신청 양식 링크가 이어졌습니다3059* 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:`으로 표시되고 그 뒤에 예외 신청 양식 링크가 이어졌습니다
3009 3060
3010### 안전 장치가 Claude의 추론을 요청하는 것으로 플래그 지정함3061### Claude의 추론을 요청하는 요청이 세이프가드에 의해 플래그됨
3011 3062
3012안전 장치가 요청을 모델의 내부 추론을 응답에 재현하도록 요구하는 것으로 플래그 지정하여 API가 요청을 거부했습니다. API는 이 [거부 범주](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#refusal-response)를 `reasoning_extraction`이라고 부르며, 거부 메시지에는 다음 줄이 포함됩니다.3063세이프가드가 요청을 모델의 내부 추론을 응답에 재현하도록 요구하는 것으로 플래그했기 때문에 API가 요청을 거부했습니다. API는 이 [거부 범주](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#refusal-response)를 `reasoning_extraction`이라고 부르며, 거부 메시지에는 다음 줄이 포함됩니다.
3013 3064
3014```text theme={null}3065```text theme={null}
3015Details: `[reasoning_extraction]`3066Details: `[reasoning_extraction]`
3019 3070
3020**해결 방법:**3071**해결 방법:**
3021 3072
3022* Claude에게 사고나 추론을 그대로 또는 고정된 형식으로 작성하도록 요청하는 지시(예: `<thinking>` 섹션, 스크래치패드 섹션, JSON 출력의 `reasoning` 필드)를 제거하거나 다르게 표현합니다. 이러한 지시는 프롬프트에 있을 수도 있고, CLAUDE.md, 스킬, 서브에이전트 프롬프트, 출력 스타일, MCP 도구 설명처럼 Claude Code가 함께 로드하는 사용자 지정 항목에 있을 수도 있습니다.3073* Claude에게 사고 또는 추론을 그대로 또는 고정된 형식으로 작성하도록 요청하는 지시를 제거하거나 표현을 바꾸십시오. 예를 들어 `<thinking>` 섹션, 스크래치패드 섹션, JSON 출력의 `reasoning` 필드 등이 있습니다. 이러한 지시는 프롬프트에 있을 수도 있고, CLAUDE.md, 스킬, 서브에이전트 프롬프트, 출력 스타일, MCP 도구 설명처럼 Claude Code가 프롬프트와 함께 로드하는 사용자 지정 항목에 있을 수도 있습니다.
3023* 사용자 지정 항목이 원인인지 확인하려면 터미널에서 [`claude --safe-mode`](https://code.claude.com/docs/ko/cli-reference#cli-flags)를 실행하여 사용자 지정 항목이 비활성화된 세션을 시작한 다음 같은 프롬프트를 보냅니다3074* 사용자 지정 항목이 원인인지 확인하려면 터미널에서 [`claude --safe-mode`](https://code.claude.com/docs/ko/cli-reference#cli-flags)를 실행하여 사용자 지정 항목이 비활성화된 세션을 시작한 다음 같은 프롬프트를 보내십시오
3024* 사용자 지정 항목을 변경한 후에는 새 세션을 시작합니다3075* 사용자 지정 항목을 변경한 후에는 새 세션을 시작하십시오
3025* 이미 보낸 프롬프트를 다르게 표현하려면 [되감기 및 요약](https://code.claude.com/docs/ko/checkpointing.md#rewind-and-summarize)을 참조하세요3076* 이미 보낸 프롬프트의 표현을 바꾸려면 [되감기 및 요약](https://code.claude.com/docs/ko/checkpointing.md#rewind-and-summarize)을 참조하십시오
3026* Claude에게 답변에 대한 설명을 요청하는 것은 여전히 가능합니다. 간단한 설명, 결과의 근거, 수행한 작업의 요약을 요청하세요. Claude의 사고 요약을 읽으려면 [`showThinkingSummaries`](https://code.claude.com/docs/ko/settings-reference#showthinkingsummaries)를 참조하세요.3077* Claude에게 답변을 설명해 달라고 요청하는 것은 여전히 가능합니다. 간단한 설명, 결과의 근거, 또는 수행한 작업의 요약을 요청하십시오. Claude의 사고 요약을 보려면 [`showThinkingSummaries`](https://code.claude.com/docs/ko/settings-reference#showthinkingsummaries)를 참조하십시오.
3027* 더 많은 예시와 다르게 표현한 요청이 여전히 거부될 때의 해결 방법은 [추론을 thinking 블록에 유지하기](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#keep-reasoning-in-thinking-blocks)를 참조하세요3078* 더 많은 예시와 표현을 바꾼 요청이 여전히 거부될 때의 해결 방법은 [추론을 thinking 블록에 유지하기](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#keep-reasoning-in-thinking-blocks)를 참조하십시오
3028 3079
3029### Output blocked by content filtering policy3080### Output blocked by content filtering policy
3030 3081
3031API의 출력 콘텐츠 필터가 Claude가 생성 중이던 응답을 중단했습니다. 메시지 텍스트는 API에서 제공됩니다.3082API의 출력 콘텐츠 필터가 Claude가 생성하던 응답을 중단했습니다. 메시지 텍스트는 API에서 제공됩니다.
3032 3083
3033```text theme={null}3084```text theme={null}
3034API Error: Output blocked by content filtering policy3085API Error: Output blocked by content filtering policy
3036 3087
3037**해결 방법:**3088**해결 방법:**
3038 3089
3039* 마지막 메시지를 다르게 표현하거나 다른 방식으로 접근합니다3090* 마지막 메시지의 표현을 바꾸거나 다른 접근 방식을 사용하십시오
3040* 차단을 유발한 턴 이전의 체크포인트로 되돌아가려면 Esc를 두 번 누르거나 `/rewind`를 실행합니다. [체크포인트](https://code.claude.com/docs/ko/checkpointing.md)를 참조하세요3091* 차단을 트리거한 턴 이전의 체크포인트로 되돌아가려면 Esc를 두 번 누르거나 `/rewind`를 실행하십시오. [체크포인트](https://code.claude.com/docs/ko/checkpointing.md)를 참조하십시오
3041 3092
3042## 명령줄 오류3093## 명령줄 오류
3043 3094
3044이러한 오류는 `claude` 명령줄과 그 하위 명령, 프롬프트에 제출한 명령 이름, 그리고 `/security-review`처럼 프롬프트가 실행되기 전에 셸 명령을 실행하여 컨텍스트를 수집하는 명령에서 발생합니다. CLI를 다시 시작하는 `/tui`에서도 발생합니다.3095이 오류는 `claude` 명령줄과 그 하위 명령, 프롬프트에서 제출한 명령 이름, 그리고 `/security-review`처럼 프롬프트가 실행되기 전에 셸 명령을 실행해 컨텍스트를 수집하는 명령에서 발생합니다. CLI를 다시 시작하는 `/tui`에서도 발생합니다.
3045 3096
3046### `--bg`와 `--print` 간의 충돌3097### `--bg`와 `--print` 간 충돌
3047 3098
3048이 메시지는 Claude Code v2.1.198 이상이 필요합니다. 같은 `claude` 호출에서 `--bg`를 `-p` 또는 `--print`와 함께 사용했습니다. `--bg`는 나중에 `claude agents`로 연결하는 [백그라운드 세션](https://code.claude.com/docs/ko/agent-view.md#from-your-shell)을 시작하는 반면, `--print`는 [비대화형으로](https://code.claude.com/docs/ko/headless.md) 실행되며 `claude agents`가 연결하는 대화형 세션을 시작하지 않습니다. v2.1.198 이전에는 이 조합이 아무런 알림 없이 연결할 수 없는 백그라운드 작업을 생성했습니다.3099이 메시지는 Claude Code v2.1.198 이상에서 나타납니다. 동일한 `claude` 호출에서 `--bg`를 `-p` 또는 `--print`와 함께 사용했습니다. `--bg`는 나중에 `claude agents`로 연결하는 [백그라운드 세션](https://code.claude.com/docs/ko/agent-view.md#from-your-shell)을 시작하는 반면, `--print`는 [비대화형으로](https://code.claude.com/docs/ko/headless.md) 실행되며 `claude agents`가 연결하는 대화형 세션을 시작하지 않습니다. v2.1.198 이전에는 이 조합이 연결할 수 없는 백그라운드 작업을 아무 알림 없이 생성했습니다.
3049 3100
3050```text theme={null}3101```text theme={null}
3051--bg and --print conflict: --print never starts the interactive session that `claude agents` attaches to, so the job would be unattachable. The prompt is the positional — drop --print: `claude --bg '<task>'`.3102--bg and --print conflict: --print never starts the interactive session that `claude agents` attaches to, so the job would be unattachable. The prompt is the positional — drop --print: `claude --bg '<task>'`.
3053 3104
3054**해결 방법:**3105**해결 방법:**
3055 3106
3056* `-p` 또는 `--print`를 제거합니다. `--bg`는 프롬프트를 위치 인수로 받으므로 `claude --bg "<task>"`만으로 완전한 명령이 됩니다. [셸에서 새 에이전트 Dispatch하기](https://code.claude.com/docs/ko/agent-view.md#from-your-shell)를 참조하십시오.3107* `-p` 또는 `--print`를 제거합니다. `--bg`는 프롬프트를 위치 인수로 받으므로 `claude --bg "<task>"`가 완전한 명령입니다. [셸에서 새 에이전트 디스패치하기](https://code.claude.com/docs/ko/agent-view.md#from-your-shell)를 참조하세요.
3057* 백그라운드 세션을 만드는 대신 프롬프트를 비대화형으로 실행하고 결과를 출력하려면 `--bg`를 제거하고 `claude -p "<task>"`를 실행합니다3108* 백그라운드 세션을 만드는 대신 프롬프트를 비대화형으로 실행하고 결과를 출력하려면 `--bg`를 제거하고 `claude -p "<task>"`를 실행합니다
3058 3109
3059### Couldn't tell whether `--bg` is a flag or text3110### Couldn't tell whether `--bg` is a flag or text
3060 3111
3061`claude`를 실행할 때 `--bg` 또는 `--background`를 Claude Code가 백그라운드 플래그인지 텍스트인지 구분할 수 없는 위치에 넣은 경우입니다. 이 명령은 아무것도 시작하지 않고 다음 줄을 출력한 뒤 종료 코드 1로 종료되었습니다:3112Claude Code가 백그라운드 플래그인지 텍스트인지 구분할 수 없는 위치에 `--bg` 또는 `--background`를 넣어 `claude`를 실행했습니다. 명령은 아무것도 시작하지 않고 다음 줄을 출력한 뒤 종료 코드 1로 종료되었습니다.
3062 3113
3063```text theme={null}3114```text theme={null}
3064Couldn't tell whether --bg is a flag or text here, so nothing was started. To start a background session put it first: claude --bg <prompt>3115Couldn't tell whether --bg is a flag or text here, so nothing was started. To start a background session put it first: claude --bg <prompt>
3065```3116```
3066 3117
3067`--background`를 입력한 경우에는 이 줄에 `--background`가 표시됩니다.3118`--background`를 입력한 경우 이 줄에는 `--background`가 대신 표시됩니다.
3068 3119
3069**해결 방법:**3120**해결 방법:**
3070 3121
3071* [백그라운드 세션](https://code.claude.com/docs/ko/agent-view.md#from-your-shell)을 시작하려면 셸에서 플래그를 맨 앞에 두고 명령을 다시 실행합니다: `claude --bg --name nightly-audit "<task>"`3122* [백그라운드 세션](https://code.claude.com/docs/ko/agent-view.md#from-your-shell)을 시작하려면 셸에서 플래그를 맨 앞에 두고 명령을 다시 실행합니다: `claude --bg --name nightly-audit "<task>"`
3072 3123
3073### 시스템 프롬프트 플래그와 파일 형식 간의 충돌3124### 시스템 프롬프트 플래그와 파일 형식 간 충돌
3074 3125
3075하나의 `claude` 호출에서 [`--append-subagent-system-prompt`](https://code.claude.com/docs/ko/cli-reference#cli-flags)와 `--append-subagent-system-prompt-file`을 함께 전달했기 때문에 `claude`가 세션을 시작하지 않고 종료 코드 1로 종료됩니다:3126하나의 `claude` 호출에서 [`--append-subagent-system-prompt`](https://code.claude.com/docs/ko/cli-reference#cli-flags)를 `--append-subagent-system-prompt-file`과 함께 전달했기 때문에 `claude`가 세션을 시작하지 않고 종료 코드 1로 종료됩니다.
3076 3127
3077```text theme={null}3128```text theme={null}
3078Error: Cannot use both --append-subagent-system-prompt and --append-subagent-system-prompt-file. Please use only one.3129Error: Cannot use both --append-subagent-system-prompt and --append-subagent-system-prompt-file. Please use only one.
3079```3130```
3080 3131
3081v2.1.283 이전에는 `--system-prompt`와 `--system-prompt-file`, 또는 `--append-system-prompt`와 `--append-system-prompt-file`을 함께 전달했을 때도 `claude`가 같은 방식으로 종료되었습니다. 이러한 쌍이 [결합](https://code.claude.com/docs/ko/cli-reference.md#system-prompt-flags)되지 않고 충돌했기 때문입니다. 해당 버전에서는 메시지에 함께 사용한 쌍이 표시됩니다.3132v2.1.283 이전에는 `--system-prompt`와 `--system-prompt-file`, 또는 `--append-system-prompt`와 `--append-system-prompt-file`을 함께 전달해도 `claude`가 같은 방식으로 종료되었습니다. 해당 쌍이 [결합](https://code.claude.com/docs/ko/cli-reference.md#system-prompt-flags)되지 않고 충돌했기 때문입니다. 해당 버전에서는 메시지에 함께 사용한 쌍의 이름이 표시됩니다.
3082 3133
3083**해결 방법:**3134**해결 방법:**
3084 3135
3085* 플래그의 한 가지 형식만 유지하고 다른 하나는 제거합니다. 고정된 프롬프트 파일과 실행별 텍스트를 결합하려면 두 플래그를 모두 전달하는 대신 실행 전에 텍스트를 파일에 병합합니다3136* 플래그 중 한 가지 형식만 남기고 다른 하나는 제거합니다. 고정된 프롬프트 파일과 실행별 텍스트를 결합하려면 두 플래그를 모두 전달하는 대신 실행 전에 텍스트를 파일에 병합합니다
3086 3137
3087### 잘못된 `--agents` 구성3138### Invalid `--agents` configuration
3088 3139
3089`--agents`에 전달한 값이 잘못되어 `claude`가 세션을 시작하지 않고 종료 코드 1로 종료됩니다. `--safe-mode`를 전달하거나 [`CLAUDE_CODE_SAFE_MODE`](https://code.claude.com/docs/ko/env-vars#variables)를 설정하면 Claude Code는 `--agents`를 완전히 무시합니다. `--resume` 또는 `--continue`를 사용하면 인라인 JSON 값은 검사되지 않고 세션이 시작되지만, 파일에서 읽은 값은 매번 실행할 때마다 검사됩니다. v2.1.242 이전에는 Claude Code가 그래도 세션을 시작했습니다.3140`--agents`에 전달한 값이 유효하지 않으므로 `claude`가 세션을 시작하지 않고 종료 코드 1로 종료됩니다. `--safe-mode`를 전달하거나 [`CLAUDE_CODE_SAFE_MODE`](https://code.claude.com/docs/ko/env-vars#variables)를 설정하면 Claude Code는 `--agents`를 완전히 무시합니다. `--resume` 또는 `--continue`를 사용하면 인라인 JSON 값은 검사되지 않고 세션이 시작되지만, 파일에서 읽은 값은 실행할 때마다 검사됩니다. v2.1.242 이전에는 Claude Code가 그대로 세션을 시작했습니다.
3090 3141
3091```text theme={null}3142```text theme={null}
3092Error: Invalid --agents configuration:3143Error: Invalid --agents configuration:
3093<what failed>3144<what failed>
3094```3145```
3095 3146
3096첫 번째 줄 다음에 오는 내용은 값이 실패한 방식에 따라 달라집니다. Claude Code는 다음 검사를 순서대로 실행하고 처음 실패한 검사에서 멈춥니다. 값에 두 종류의 문제가 있으면 첫 번째 문제를 수정한 후에야 두 번째 문제가 표시됩니다:3147첫 번째 줄 다음에 오는 내용은 값이 실패한 방식에 따라 달라집니다. Claude Code는 다음 검사를 순서대로 실행하며 처음 실패한 검사에서 멈춥니다. 값에 두 종류의 문제가 있으면 첫 번째 문제를 수정한 후에야 두 번째 문제가 표시됩니다.
3097 3148
30981. 값이 `{`로 시작하지만 JSON으로 파싱되지 않거나 `--agents` 파일의 내용이 파싱되지 않으면, Claude Code는 JSON 파서 자체의 메시지를 담은 `invalid JSON:` 줄 하나를 출력합니다31491. 값이 `{`로 시작하지만 JSON으로 구문 분석되지 않거나 `--agents` 파일의 내용이 구문 분석되지 않으면, Claude Code는 JSON 파서 자체의 메시지가 포함된 `invalid JSON:` 줄 하나를 출력합니다
30992. 파싱은 되지만 에이전트 정의가 [CLI로 정의한 서브에이전트](https://code.claude.com/docs/ko/sub-agents.md#choose-the-subagent-scope)의 스키마와 일치하지 않으면, Claude Code는 문제마다 한 줄씩 출력합니다31502. 구문 분석은 되지만 에이전트 정의가 [CLI로 정의한 서브에이전트](https://code.claude.com/docs/ko/sub-agents.md#choose-the-subagent-scope)의 스키마와 일치하지 않으면, Claude Code는 문제마다 한 줄씩 출력합니다
31003. 에이전트 이름이 `-`로 시작하면 Claude Code는 `<name>: agent names must not start with '-'`를 출력합니다31513. 에이전트 이름이 `-`로 시작하면 Claude Code는 `<name>: agent names must not start with '-'`를 출력합니다
3101 3152
3102문제 줄이 20개를 넘으면 Claude Code는 처음 20개를 출력하고 나머지는 `…and N more`로 대체합니다.3153문제 줄이 20개를 넘으면 Claude Code는 처음 20개를 출력하고 나머지는 `…and N more`로 대체합니다.
3103 3154
3104`--print`와 함께 사용하면 `--agents`는 인라인 객체 대신 [JSON 파일 경로](https://code.claude.com/docs/ko/sub-agents.md#choose-the-subagent-scope)도 받습니다. v2.1.281 이전에는 `--agents`가 인라인 JSON만 받았으며 파일 경로를 잘못된 JSON으로 처리했습니다. 파일 형식에는 자체적인 거부 메시지가 있으며, 이 메시지 대신 출력됩니다. 다음은 그 예입니다:3155`--print`를 사용하면 `--agents`는 인라인 객체 대신 [JSON 파일 경로](https://code.claude.com/docs/ko/sub-agents.md#choose-the-subagent-scope)도 받습니다. v2.1.281 이전에는 `--agents`가 인라인 JSON만 받았으며 파일 경로를 잘못된 JSON으로 처리했습니다. 파일 형식에는 자체 거부 메시지가 있으며, 이 메시지 대신 다음과 같은 메시지가 출력됩니다.
3105 3156
3106* **`Error: --agents takes a JSON object, or a file path only with --print (-p)`**: Claude Code가 대화형 세션에서 값을 파일 경로로 읽었습니다. 정의를 인라인 JSON으로 전달하거나, 파일에서 읽으려면 `-p`를 추가합니다.3157* **`Error: --agents takes a JSON object, or a file path only with --print (-p)`**: 대화형 세션에서 Claude Code가 값을 파일 경로로 읽었습니다. 정의를 인라인 JSON으로 전달하거나, 파일에서 읽으려면 `-p`를 추가합니다.
3107* **`Error: --agents file not found: <path>`**: 해당 경로에 파일이 없습니다. `{`로 시작하지 않고 유효한 JSON이 아닌 값은 경로로 읽히므로, 셸이 망가뜨린 인라인 JSON도 이런 방식으로 실패할 수 있습니다. 경로나 따옴표 처리를 확인하고 명령을 다시 실행합니다.3158* **`Error: --agents file not found: <path>`**: 해당 경로에 파일이 없습니다. `{`로 시작하지 않고 유효한 JSON이 아닌 값은 경로로 읽히므로, 셸이 손상시킨 인라인 JSON도 이런 방식으로 실패할 수 있습니다. 경로나 따옴표 처리를 확인하고 명령을 다시 실행합니다.
3108 3159
3109**해결 방법:**3160**해결 방법:**
3110 3161
3111* 메시지에 나열된 각 문제를 수정한 다음 명령을 다시 실행합니다. [CLI로 정의한 서브에이전트가 받는 필드](https://code.claude.com/docs/ko/sub-agents.md#choose-the-subagent-scope)를 참조하십시오.3162* 메시지에 나열된 각 문제를 수정한 다음 명령을 다시 실행합니다. [CLI로 정의한 서브에이전트가 받는 필드](https://code.claude.com/docs/ko/sub-agents.md#choose-the-subagent-scope)를 참조하세요.
3112 3163
3113### `--restricted` 세션에서는 클라우드 세션을 만들 수 없음3164### Cloud sessions cannot be created from a `--restricted` session
3114 3165
3115[`--restricted`](https://code.claude.com/docs/ko/cli-reference#cli-flags)로 세션을 시작하면 Claude Code는 해당 세션에서 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md#from-terminal-to-cloud)을 만드는 것을 거부합니다. 새 세션은 제한된 프로세스 외부에서 실행되어 제한 모드를 적용하지 않기 때문입니다. Claude Code는 서버에 연결하기 전에 클라이언트에서 거부하므로 클라우드 세션이 생성되지 않습니다:3166[`--restricted`](https://code.claude.com/docs/ko/cli-reference#cli-flags)로 세션을 시작하면 Claude Code는 해당 세션에서 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md#from-terminal-to-cloud)을 만드는 것을 거부합니다. 새 세션은 제한된 프로세스 외부에서 실행되어 제한 모드를 적용하지 않기 때문입니다. Claude Code는 서버에 연결하기 전에 클라이언트에서 거부하므로 클라우드 세션은 생성되지 않습니다.
3116 3167
3117```text theme={null}3168```text theme={null}
3118Cloud sessions cannot be created from a --restricted session: they would not enforce it.3169Cloud sessions cannot be created from a --restricted session: they would not enforce it.
3121**해결 방법:**3172**해결 방법:**
3122 3173
3123* 제한된 세션에서 작업을 로컬로 실행합니다3174* 제한된 세션에서 작업을 로컬로 실행합니다
3124* 세션 실행 방식을 제어할 수 있다면 `--restricted` 없이 새 `claude` 세션을 시작하고 그곳에서 클라우드 세션을 만듭니다3175* 세션이 시작되는 방식을 제어할 수 있다면 `--restricted` 없이 새 `claude` 세션을 시작하고 그곳에서 클라우드 세션을 만듭니다
3125 3176
3126v2.1.248 이전의 Claude Code에는 `--restricted` 플래그가 없었으며, 이전 버전은 알 수 없는 옵션 오류로 플래그 자체를 거부합니다.3177v2.1.248 이전에는 Claude Code에 `--restricted` 플래그가 없었으며, 이전 버전은 알 수 없는 옵션 오류로 플래그 자체를 거부합니다.
3127 3178
3128### 조직 정책에 의해 클라우드 세션이 비활성화됨3179### Cloud sessions are disabled by your organization's policy
3129 3180
3130조직의 `allow_remote_sessions` 정책이 꺼져 있어 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)과 이를 사용하는 명령을 사용할 수 없습니다:3181조직의 `allow_remote_sessions` 정책이 꺼져 있으므로 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)과 이를 사용하는 명령을 사용할 수 없습니다.
3131 3182
3132```text theme={null}3183```text theme={null}
3133Cloud sessions are disabled by your organization's policy. Contact your organization admin to enable them.3184Cloud sessions are disabled by your organization's policy. Contact your organization admin to enable them.
3134```3185```
3135 3186
3136이 메시지는 [터미널에서 클라우드 세션을 만들 때](https://code.claude.com/docs/ko/claude-code-on-the-web.md#from-terminal-to-cloud)와 `/teleport`, `/remote-env`, `/web-setup`처럼 클라우드 세션이 필요한 명령을 제출할 때 표시됩니다. v2.1.268 이전에는 이러한 명령을 제출하면 대신 [`Unknown command`](#unknown-command)가 반환되었습니다.3187이 메시지는 [터미널에서 클라우드 세션을 만들 때](https://code.claude.com/docs/ko/claude-code-on-the-web.md#from-terminal-to-cloud)와 `/teleport`, `/remote-env`, `/web-setup`처럼 클라우드 세션이 필요한 명령을 제출할 때 나타납니다. v2.1.268 이전에는 이러한 명령을 제출하면 대신 [`Unknown command`](#unknown-command)가 반환되었습니다.
3137 3188
3138메시지가 대신 이 세션에서 사용 중인 자격 증명을 지목하고 `Cloud sessions use your claude.ai login.`으로 끝나는 경우, [Cloud sessions use your claude.ai login](#cloud-sessions-use-your-claude-ai-login)을 참조하십시오. Claude Code가 조직의 정책을 전혀 로드하지 못한 경우에는 대신 [다른 메시지](#couldnt-verify-your-organizations-policy-for-cloud-sessions)가 표시됩니다.3189메시지에 이 세션이 사용 중인 자격 증명이 표시되고 `Cloud sessions use your claude.ai login.`으로 끝나는 경우 [Cloud sessions use your claude.ai login](#cloud-sessions-use-your-claude-ai-login)을 참조하세요. Claude Code가 조직의 정책을 전혀 불러오지 못한 경우에는 대신 [다른 메시지](#couldnt-verify-your-organizations-policy-for-cloud-sessions)가 표시됩니다.
3139 3190
3140**해결 방법:**3191**해결 방법:**
3141 3192
3142* 조직의 [Owner](https://code.claude.com/docs/ko/server-managed-settings.md#access-control)에게 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)의 Claude Code 관리자 설정에서 클라우드 세션을 활성화하도록 요청합니다3193* 조직의 [Owner](https://code.claude.com/docs/ko/server-managed-settings.md#access-control)에게 [claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)의 Claude Code 관리자 설정에서 클라우드 세션을 활성화해 달라고 요청합니다
3143 3194
3144### Cloud sessions use your claude.ai login3195### Cloud sessions use your claude.ai login
3145 3196
3146[정책 거부](#cloud-sessions-are-disabled-by-your-organizations-policy) 메시지가 이 세션에서 사용 중인 자격 증명을 지목하고 이 문장으로 끝나는 경우, Claude Code는 해당 자격 증명을 발급한 조직의 클라우드 세션 정책을 확인한 것입니다. 그 조직은 claude.ai 로그인이 속한 조직과 다를 수 있습니다:3197[정책 거부](#cloud-sessions-are-disabled-by-your-organizations-policy) 메시지에 이 세션이 사용 중인 자격 증명이 표시되고 이 문장으로 끝나는 경우, Claude Code는 해당 자격 증명을 발급한 조직의 클라우드 세션 정책을 확인한 것입니다. 이 조직은 claude.ai 로그인이 속한 조직과 다를 수 있습니다.
3147 3198
3148```text theme={null}3199```text theme={null}
3149Cloud sessions are disabled by your organization's policy. This session is using ANTHROPIC_API_KEY, so Claude Code checked the policy for the organization that key belongs to. Cloud sessions use your claude.ai login.3200Cloud sessions are disabled by your organization's policy. This session is using ANTHROPIC_API_KEY, so Claude Code checked the policy for the organization that key belongs to. Cloud sessions use your claude.ai login.
3153 3204
3154### Couldn't verify your organization's policy for cloud sessions3205### Couldn't verify your organization's policy for cloud sessions
3155 3206
3156이 메시지들은 Claude Code가 조직의 정책을 로드하지 못했음을 의미합니다. Claude Code는 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)을 생성하거나, 재개하거나, 메시지를 보내기 전에 이 정책을 확인합니다. 정책 요청이 아직 완료되지 않은 동안에는 메시지가 다음과 같습니다:3207이 메시지는 Claude Code가 조직의 정책을 불러오지 못했다는 의미입니다. Claude Code는 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)을 만들거나, 재개하거나, 메시지를 보내기 전에 이 정책을 확인합니다. 정책 요청이 아직 완료되지 않은 동안 표시되는 메시지는 다음과 같습니다.
3157 3208
3158```text theme={null}3209```text theme={null}
3159Couldn't verify your organization's policy for cloud sessions. Check your network connection and try again.3210Couldn't verify your organization's policy for cloud sessions. Check your network connection and try again.
3160```3211```
3161 3212
3162세션 내에서 `/teleport`나 `/web-setup`처럼 클라우드 세션이 필요한 명령도 이 메시지를 표시합니다. 셸이라면 `Cloud sessions aren't available:` 형식을 출력할 상황에서도 마찬가지이며, 두 번째 문장은 `Check your network connection, then restart Claude Code and try again.`입니다.3213세션 내에서 `/teleport`나 `/web-setup`처럼 클라우드 세션이 필요한 명령도 이 메시지를 표시합니다. 셸이라면 `Cloud sessions aren't available:` 형식을 출력할 상황에서도 이 메시지가 표시되며, 두 번째 문장은 `Check your network connection, then restart Claude Code and try again.`입니다.
3163 3214
3164정책 요청이 실패하면 메시지에 무엇이 실패했는지가 표시됩니다. 이는 `--cloud` 또는 `--teleport` 같은 플래그로 셸에서 클라우드 세션을 시작하거나, 재개하거나, 메시지를 보낼 때 적용됩니다. API에 연결할 경로가 없으면 다음과 같이 표시됩니다:3215정책 요청이 실패하면 메시지에 실패한 내용이 표시됩니다. 이는 `--cloud` 또는 `--teleport` 같은 플래그로 셸에서 클라우드 세션을 시작하거나, 재개하거나, 메시지를 보낼 때 적용됩니다. API로 가는 경로가 없으면 다음과 같이 표시됩니다.
3165 3216
3166```text theme={null}3217```text theme={null}
3167Cloud sessions aren't available: couldn't reach api.anthropic.com to load your organization's policy. Check your network or proxy.3218Cloud sessions aren't available: couldn't reach api.anthropic.com to load your organization's policy. Check your network or proxy.
3168```3219```
3169 3220
3170다른 실패도 같은 시작 문구 뒤에 HTTP 403으로 요청을 거부한 프록시, 서버 오류, API가 받아들이지 않은 자격 증명 등 각자의 원인이 이어집니다. 이 세션이 claude.ai 로그인 대신 사용하는 자격 증명(예: `ANTHROPIC_API_KEY` 환경 변수)을 API가 받아들이지 않은 경우, 메시지에 해당 자격 증명이 지목되고 설정을 해제하라는 안내가 포함될 수도 있습니다:3221다른 실패도 같은 시작 부분 뒤에 HTTP 403으로 요청을 거부한 프록시, 서버 오류, API가 받아들이지 않은 자격 증명 등 각각의 원인이 이어집니다. 이 세션이 claude.ai 로그인 대신 사용하는 자격 증명(예: `ANTHROPIC_API_KEY` 환경 변수)을 API가 받아들이지 않은 경우, 메시지에 해당 자격 증명의 이름과 설정을 해제하라는 안내가 표시될 수도 있습니다.
3171 3222
3172```text theme={null}3223```text theme={null}
3173Cloud sessions aren't available: api.anthropic.com didn't accept this session's credentials when Claude Code asked for your organization's policy. Cloud sessions use your claude.ai login. ANTHROPIC_API_KEY is set, so this session is using API-key auth — unset it (or run in a shell without it) to use cloud sessions.3224Cloud sessions aren't available: api.anthropic.com didn't accept this session's credentials when Claude Code asked for your organization's policy. Cloud sessions use your claude.ai login. ANTHROPIC_API_KEY is set, so this session is using API-key auth — unset it (or run in a shell without it) to use cloud sessions.
3174```3225```
3175 3226
3176v2.1.296 이전에는 이러한 실패에서도 `Couldn't verify` 메시지가 출력되었습니다.3227v2.1.296 이전에는 이러한 실패에도 `Couldn't verify` 메시지가 출력되었습니다.
3177 3228
3178**해결 방법:**3229**해결 방법:**
3179 3230
3180* `Couldn't verify` 메시지의 경우 네트워크 연결을 확인하고 다시 시도합니다. 세션 내라면 먼저 Claude Code를 다시 시작합니다3231* `Couldn't verify` 메시지의 경우 네트워크 연결을 확인하고 다시 시도합니다. 세션 내에서는 먼저 Claude Code를 다시 시작합니다
3181* `Cloud sessions aren't available:` 메시지의 경우 프록시 확인이나 메시지가 지목한 자격 증명의 설정 해제 등 원인에 맞는 조치를 취한 다음 명령을 다시 실행합니다3232* `Cloud sessions aren't available:` 메시지의 경우 프록시 확인이나 메시지에 표시된 자격 증명 설정 해제 등 원인에 맞는 조치를 취한 다음 명령을 다시 실행합니다
3182 3233
3183### 폴더가 추적 중인 파일을 대체하여 아무것도 stash되지 않음3234### 폴더가 추적 파일을 대체하여 아무것도 stash되지 않음
3184 3235
3185이 메시지는 체크아웃에서 git이 추적하던 파일이나 링크가 있던 자리에 이제 폴더가 있다는 의미입니다. 예를 들어 `claude --teleport` 또는 `/teleport`로 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md#from-cloud-to-terminal)을 터미널로 가져오는 중에 stash 옵션을 선택한 후 나타납니다. 이 상태를 stash하면 폴더 안의 파일이 삭제될 수 있으므로, Claude Code는 stash를 거부하고 체크아웃과 인덱스를 변경하지 않은 채 둡니다:3236이 메시지는 체크아웃에서 git이 추적하던 파일이나 링크가 있던 위치에 이제 폴더가 있다는 의미입니다. `claude --teleport` 또는 `/teleport` 등으로 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md#from-cloud-to-terminal)을 터미널로 가져오는 중에 stash 옵션을 선택한 후 나타납니다. 이 상태를 stash하면 폴더 안의 파일이 삭제될 수 있으므로 Claude Code는 stash를 거부하고 체크아웃과 인덱스를 변경하지 않고 그대로 둡니다.
3186 3237
3187```text wrap theme={null}3238```text wrap theme={null}
3188Error: Nothing was stashed: "f" is now a folder in place of a tracked file or link, and stashing could delete what's in it for good. Commit the change or move the folder somewhere else, then try again.3239Error: Nothing was stashed: "f" is now a folder in place of a tracked file or link, and stashing could delete what's in it for good. Commit the change or move the folder somewhere else, then try again.
3190 3241
3191**해결 방법:**3242**해결 방법:**
3192 3243
3193* 메시지에 안내된 대로 변경 사항을 커밋하거나 폴더를 다른 곳으로 옮긴 다음 teleport를 다시 실행합니다3244* 메시지 안내대로 변경 사항을 커밋하거나 폴더를 다른 곳으로 옮긴 다음 teleport를 다시 실행합니다
3194 3245
3195### `--json-schema` 값이 유효한 JSON Schema가 아님3246### The `--json-schema` value is not a valid JSON Schema
3196 3247
3197[비대화형 모드](https://code.claude.com/docs/ko/headless.md#get-structured-output)에서 [`--json-schema`](https://code.claude.com/docs/ko/cli-reference#cli-flags)에 전달한 스키마가 JSON Schema 컴파일에 실패하여 `claude`가 프롬프트를 실행하지 않고 종료 코드 1로 종료됩니다. v2.1.205 이전에는 잘못된 스키마가 오류 없이 구조화되지 않은 출력을 생성했으며, `format` 키워드를 사용하는 스키마는 모두 잘못된 것으로 처리되었습니다.3248[비대화형 모드](https://code.claude.com/docs/ko/headless.md#get-structured-output)에서 [`--json-schema`](https://code.claude.com/docs/ko/cli-reference#cli-flags)에 전달한 스키마가 JSON Schema 컴파일에 실패했으므로 `claude`가 프롬프트를 실행하지 않고 종료 코드 1로 종료됩니다. v2.1.205 이전에는 잘못된 스키마가 오류 없이 구조화되지 않은 출력을 생성했으며, `format` 키워드를 사용한 스키마는 모두 유효하지 않은 것으로 처리되었습니다.
3198 3249
3199```text theme={null}3250```text theme={null}
3200Error: --json-schema is not a valid JSON Schema: data/type must be equal to one of the allowed values3251Error: --json-schema is not a valid JSON Schema: data/type must be equal to one of the allowed values
3201```3252```
3202 3253
3203두 번째 콜론 뒤의 텍스트는 검증기의 진단 내용이며 실패한 키워드나 위치를 알려 줍니다. `"format": "email"`처럼 `format` 키워드를 사용하는 스키마는 유효합니다. Claude Code는 `format`을 주석으로 받아들이며 이를 강제하지 않습니다.3254두 번째 콜론 뒤의 텍스트는 검증기의 진단 메시지이며 실패한 키워드나 위치를 나타냅니다. `"format": "email"`처럼 `format` 키워드를 사용하는 스키마는 유효합니다. Claude Code는 `format`을 주석으로 받아들이며 이를 강제하지 않습니다.
3204 3255
3205Claude Code는 스키마 컴파일 전에 두 가지 검사를 실행합니다. 파싱할 수 없는 JSON 값은 `Error: --json-schema is not valid JSON`으로 거부하고, 객체가 아닌 유효한 JSON은 `Error: --json-schema must be a JSON object`로 거부합니다.3256Claude Code는 스키마 컴파일 전에 두 가지 검사를 실행합니다. 구문 분석할 수 없는 JSON 값은 `Error: --json-schema is not valid JSON`으로, 객체가 아닌 유효한 JSON은 `Error: --json-schema must be a JSON object`로 거부합니다.
3206 3257
3207**해결 방법:**3258**해결 방법:**
3208 3259
3209* 진단 내용이 가리키는 스키마 부분을 수정한 다음 명령을 다시 실행합니다3260* 진단 메시지가 가리키는 스키마 부분을 수정한 다음 명령을 다시 실행합니다
3210* 작동하는 스키마와 명령은 [구조화된 출력 얻기](https://code.claude.com/docs/ko/headless.md#get-structured-output)를 참조하십시오3261* 작동하는 스키마와 명령은 [구조화된 출력 받기](https://code.claude.com/docs/ko/headless.md#get-structured-output)를 참조하세요
3211 3262
3212### 설정 파일이 2MiB 제한을 초과함3263### Settings file exceeds the 2MiB limit
3213 3264
3214[`--settings`](https://code.claude.com/docs/ko/cli-reference#cli-flags)에 전달한 파일이 2MiB보다 커서 `claude`가 파일을 로드하지 않고 시작 시 종료 코드 1로 종료됩니다. v2.1.214 이전에는 Claude Code가 크기 검사 없이 파일을 읽었기 때문에, 수 기가바이트 크기의 파일이나 `/dev/zero` 같은 장치 파일로 인해 메모리가 무한히 증가했습니다.3265[`--settings`](https://code.claude.com/docs/ko/cli-reference#cli-flags)에 전달한 파일이 2 MiB보다 크므로 `claude`가 파일을 불러오지 않고 시작 시 종료 코드 1로 종료됩니다. v2.1.214 이전에는 Claude Code가 크기 검사 없이 파일을 읽었기 때문에, 수 기가바이트 크기의 파일이나 `/dev/zero` 같은 장치 파일로 인해 메모리가 한없이 증가했습니다.
3215 3266
3216```text theme={null}3267```text theme={null}
3217Error: Settings file exceeds the 2MiB limit: /path/to/settings.json3268Error: Settings file exceeds the 2MiB limit: /path/to/settings.json
3218```3269```
3219 3270
3220Claude Code는 일반 파일이 아닌 `--settings` 경로도 같은 방식으로 거부합니다. 장치, FIFO 또는 소켓의 경우 `Error: Cannot use settings file (Not a regular file (device, FIFO, or socket))` 뒤에 경로가 표시되고, 디렉터리의 경우 `EISDIR` 사유가 표시됩니다.3271Claude Code는 일반 파일이 아닌 `--settings` 경로도 같은 방식으로 거부합니다. 장치, FIFO, 소켓은 `Error: Cannot use settings file (Not a regular file (device, FIFO, or socket))` 뒤에 경로를 표시하고, 디렉터리는 `EISDIR` 사유를 표시합니다.
3272
3273**해결 방법:**
3274
3275* `--settings`가 2 MiB 미만의 일반 JSON 설정 파일을 가리키도록 합니다. 형식은 [설정](https://code.claude.com/docs/ko/settings.md)을 참조하세요.
3276
3277### Configuration error in \~/.claude.json
3278
3279Claude Code가 계정 정보, MCP 서버, 프로젝트별 상태를 저장하는 파일인 `~/.claude.json`을 구문 분석하지 못했습니다. 파일은 변경되지 않았습니다. `claude -p` 같은 [비대화형](https://code.claude.com/docs/ko/headless.md) 시작은 파일을 복구할 때까지 매번 종료 코드 1로 종료됩니다.
3280
3281Claude Code가 [백업](https://code.claude.com/docs/ko/claude-directory.md#cleaned-up-automatically)을 찾으면 출력에 백업 이름과 이를 다시 복사하는 `cp` 줄이 표시됩니다.
3282
3283```text wrap theme={null}
3284Claude configuration file at /home/user/.claude.json is corrupted: <JSON parser's message>
3285The corrupted file has been backed up to: /home/user/.claude/backups/.claude.json.corrupted.1793664000000
3286A backup file exists at: /home/user/.claude/backups/.claude.json.backup.1793660400000
3287You can manually restore it by running: cp -f "/home/user/.claude/backups/.claude.json.backup.1793660400000" "/home/user/.claude.json"
3288
3289Configuration error in /home/user/.claude.json: <JSON parser's message>
3290```
3291
3292**해결 방법:**
3293
3294* **출력에 `cp` 줄이 있는 경우**: 터미널에서 해당 줄을 실행합니다. Windows에서는 PowerShell에서 실행합니다. 손상된 파일을 `~/.claude.json`의 이전 버전인 백업으로 대체합니다.
3295* **출력에 `cp` 줄이 없거나 실행 후에도 오류가 다시 발생하는 경우**: `~/.claude.json`의 JSON을 수정하거나, [`~/.claude/backups/`](https://code.claude.com/docs/ko/claude-directory#cleaned-up-automatically)에 다른 `.claude.json.backup.<timestamp>` 파일이 있으면 그 파일로 덮어쓰거나, 파일 이름을 변경합니다. `~/.claude.json`에 파일이 없으면 Claude Code는 기본 설정으로 시작하며 파일에 있던 내용은 모두 사용되지 않습니다.
3296
3297v2.1.318 이전에는 비대화형 시작에서 이 오류가 출력된 후 `~/.claude.json`이 기본값으로 남아, 다음 시작이 기존 구성 없이 실행되었습니다.
3298
3299### Claude configuration file was empty and no backup holds anything
3300
3301시작 시 나타나는 이 메시지는 메시지에 표시된 파일이 비어 있고 해당 파일의 [`.backup` 사본](https://code.claude.com/docs/ko/claude-directory#cleaned-up-automatically)에도 아무 내용이 없다는 의미입니다. Claude Code는 해당 파일이 담는 내용에 대해 기본값으로 시작했습니다. `settings.json` 파일과 `.mcp.json`은 별도의 파일입니다.
3302
3303```text wrap theme={null}
3304Claude configuration file at /home/user/.claude.json was empty and no backup holds anything: starting with defaults.
3305```
3221 3306
3222**해결 방법:**3307**해결 방법:**
3223 3308
3224* `--settings`가 2MiB 미만의 일반 JSON 설정 파일을 가리키도록 합니다. 형식은 [설정](https://code.claude.com/docs/ko/settings.md)을 참조하십시오.3309* 해당 파일에 구성해 두었던 내용을 다시 설정합니다. 예를 들어 터미널에서 `claude mcp add`로 `user` 및 `local` 범위의 [MCP 서버](https://code.claude.com/docs/ko/mcp.md#mcp-installation-scopes)를 추가합니다.
3310* Claude Code가 요청하면 다시 로그인합니다
3311
3312v2.1.318 이전에는 Claude Code가 백업 없는 빈 파일을 [손상됨](#configuration-error-in-claude-json)으로 보고했습니다.
3225 3313
3226### 현재 디렉터리가 더 이상 존재하지 않음3314### The current directory no longer exists
3227 3315
3228셸이 진입한 후 삭제되거나 이동된 디렉터리(예: 다른 셸이 제거한 worktree 또는 임시 디렉터리)에서 `claude`를 시작했습니다. Claude Code는 작업 디렉터리를 읽을 수 없으므로 대화형 모드와 [비대화형](https://code.claude.com/docs/ko/headless.md) 모드 모두에서 세션을 시작하기 전에 종료 코드 1로 종료됩니다. v2.1.239 이전에는 이 메시지 대신 Claude Code가 축소된 번들 소스와 원시 `ENOENT ... uv_cwd` 스택을 stderr에 출력하며 충돌했습니다.3316셸이 진입한 후 삭제되거나 이동된 디렉터리(예: 다른 셸이 제거한 worktree나 임시 디렉터리)에서 `claude`를 시작했습니다. Claude Code가 작업 디렉터리를 읽을 수 없으므로 대화형 모드와 [비대화형](https://code.claude.com/docs/ko/headless.md) 모드 모두에서 세션을 시작하기 전에 종료 코드 1로 종료됩니다. v2.1.239 이전에는 이 메시지 대신 Claude Code가 축소된 번들 소스와 원시 `ENOENT ... uv_cwd` 스택을 stderr에 출력하며 충돌했습니다.
3229 3317
3230```text theme={null}3318```text theme={null}
3231The current directory no longer exists (it was deleted or moved). Start Claude Code from an existing directory.3319The current directory no longer exists (it was deleted or moved). Start Claude Code from an existing directory.
3232error: The current working directory was deleted, so that command didn't work. Please cd into a different directory and try again.3320error: The current working directory was deleted, so that command didn't work. Please cd into a different directory and try again.
3233```3321```
3234 3322
3235두 형식 모두 원인과 해결 방법이 같습니다.3323두 형식 모두 원인과 해결 방법은 같습니다.
3236 3324
3237권한 변경 등 다른 이유로 Claude Code가 작업 디렉터리를 읽을 수 없는 경우, 메시지에는 대신 오류 코드가 표시됩니다: `Can't read the current directory (EACCES). Start Claude Code from a different directory.`3325권한 변경 등 다른 이유로 Claude Code가 작업 디렉터리를 읽을 수 없으면 메시지에 대신 오류 코드가 표시됩니다: `Can't read the current directory (EACCES). Start Claude Code from a different directory.`
3238 3326
3239macOS에서 `~/Desktop`, `~/Documents`, `~/Downloads` 또는 iCloud Drive에 있는 디렉터리에 대한 `EPERM`은 대개 macOS가 터미널 앱의 해당 폴더 접근을 차단하고 있음을 의미합니다. 해당 폴더를 읽는 다른 명령도 같은 방식으로 실패합니다. 그곳에서 `ls`를 실행하면 `sudo`를 사용하더라도 `Operation not permitted`가 표시됩니다.3327macOS에서 `~/Desktop`, `~/Documents`, `~/Downloads` 또는 iCloud Drive에 있는 디렉터리에 대해 `EPERM`이 발생하면 대개 macOS가 터미널 앱의 해당 폴더 접근을 차단하고 있다는 의미입니다. 해당 폴더를 읽는 다른 명령도 같은 방식으로 실패하며, 그곳에서 `ls`를 실행하면 `sudo`를 사용하더라도 `Operation not permitted`가 표시됩니다.
3240 3328
3241**해결 방법:**3329**해결 방법:**
3242 3330
3243* 홈 디렉터리나 프로젝트 디렉터리처럼 존재하는 디렉터리로 이동한 다음 `claude`를 다시 실행합니다3331* 홈 디렉터리나 프로젝트 디렉터리처럼 존재하는 디렉터리로 이동한 다음 `claude`를 다시 실행합니다
3244* 디렉터리가 같은 경로에 다시 생성된 경우에도 셸은 여전히 삭제된 디렉터리를 붙잡고 있습니다. `cd "$PWD"`를 실행하거나 디렉터리에서 나갔다가 다시 들어간 다음 `claude`를 다시 실행합니다3332* 디렉터리가 같은 경로에 다시 생성된 경우 셸은 여전히 삭제된 디렉터리를 가리키고 있습니다. `cd "$PWD"`를 실행하거나 디렉터리에서 나갔다가 다시 들어간 다음 `claude`를 다시 실행합니다
3245* macOS에서 `EPERM`이 발생하면 Cmd+Q로 터미널 앱을 종료하고 다시 연 다음, 해당 폴더로 돌아가 `claude`를 실행합니다. 그 폴더에서 `ls`가 여전히 실패하면 **시스템 설정 > 개인정보 보호 및 보안 > 파일 및 폴더**를 열고 터미널 앱에 대해 해당 폴더를 켠 다음 터미널을 다시 엽니다3333* macOS에서 `EPERM`이 발생하면 Cmd+Q로 터미널 앱을 종료하고 다시 연 다음, 해당 폴더로 돌아가 `claude`를 실행합니다. 그래도 해당 폴더에서 `ls`가 실패하면 **System Settings > Privacy & Security > Files and Folders**를 열고 터미널 앱에 대해 해당 폴더를 켠 다음 터미널을 다시 엽니다
3246 3334
3247### 임시 디렉터리가 거부되었거나 생성할 수 없음3335### 임시 디렉터리가 거부되었거나 생성할 수 없음
3248 3336
3249macOS와 Linux에서 Claude Code는 시작 시 시스템 임시 디렉터리 또는 [`CLAUDE_CODE_TMPDIR`](https://code.claude.com/docs/ko/env-vars) 재정의 경로 아래에 비공개 임시 디렉터리 `claude-<uid>`를 만듭니다. 디렉터리를 만들 수 없거나 해당 경로에 이미 있는 항목이 안전 검사를 통과하지 못하면, Claude Code는 세션을 시작하지 않고 실패 내용을 stderr에 출력한 후 종료 코드 1로 종료됩니다:3337macOS와 Linux에서 Claude Code는 시작 시 시스템 임시 디렉터리 또는 [`CLAUDE_CODE_TMPDIR`](https://code.claude.com/docs/ko/env-vars) 재정의 위치 아래에 전용 임시 디렉터리 `claude-<uid>`를 만듭니다. 디렉터리를 만들 수 없거나 해당 경로에 이미 있는 항목이 안전성 검사를 통과하지 못하면, Claude Code는 세션을 시작하지 않고 실패 내용을 stderr에 출력한 뒤 종료 코드 1로 종료됩니다.
3250 3338
3251```text wrap theme={null}3339```text wrap theme={null}
3252Claude Code's temporary directory /tmp/claude-501 could not be created: the volume holding /tmp is full (ENOSPC). Free space on that volume, or set CLAUDE_CODE_TMPDIR to a directory on another one, then try again.3340Claude Code's temporary directory /tmp/claude-501 could not be created: the volume holding /tmp is full (ENOSPC). Free space on that volume, or set CLAUDE_CODE_TMPDIR to a directory on another one, then try again.
3260 3348
3261**해결 방법:**3349**해결 방법:**
3262 3350
3263* `could not be created` 뒤에 `is full (ENOSPC)`가 오는 경우, 메시지에 표시된 볼륨의 디스크 공간을 확보합니다. 대신 `your disk quota on the volume holding /tmp is used up (EDQUOT)`가 표시되면 해당 볼륨에서 더 이상 필요하지 않은 자신의 파일을 삭제합니다3351* `could not be created` 뒤에 `is full (ENOSPC)`가 표시되면 메시지에 표시된 볼륨의 디스크 공간을 확보합니다. 대신 `your disk quota on the volume holding /tmp is used up (EDQUOT)`가 표시되면 해당 볼륨에서 더 이상 필요하지 않은 본인 파일을 삭제합니다
3264* `Refusing to use it` 형식의 경우 링크가 가리키는 대상이 아니라 메시지에 표시된 항목 자체를 제거하고 Claude Code를 다시 시작합니다. `owned by uid` 형식의 경우 관리자나 해당 사용자만 제거할 수 있습니다3352* `Refusing to use it` 형식의 경우 링크가 가리키는 대상이 아니라 메시지에 표시된 항목 자체를 제거하고 Claude Code를 다시 시작합니다. `owned by uid` 형식의 경우 관리자나 해당 사용자만 이를 제거할 수 있습니다
3265* `is not readable`의 경우 표시된 디렉터리에 `chmod 0700`을 실행하거나, 디렉터리를 제거하고 다시 시작합니다3353* `is not readable`의 경우 표시된 디렉터리에 `chmod 0700`을 실행하거나, 디렉터리를 제거하고 다시 시작합니다
3266* 어떤 경우든 거부된 경로는 그대로 두고 [`CLAUDE_CODE_TMPDIR`](https://code.claude.com/docs/ko/env-vars)를 직접 제어하는 디렉터리로 설정한 다음 Claude Code를 다시 시작할 수 있습니다3354* 어떤 경우든 거부된 경로는 그대로 두고 [`CLAUDE_CODE_TMPDIR`](https://code.claude.com/docs/ko/env-vars)를 직접 제어하는 디렉터리로 설정한 다음 Claude Code를 다시 시작할 수 있습니다
3267 3355
3268v2.1.309 이전에는 볼륨이 가득 차거나 할당량을 모두 사용한 경우 Claude Code가 운영 체제의 오류 텍스트만 출력했습니다. 예를 들어 `ENOSPC: no space left on device, mkdir '/tmp/claude-501'`이며, 같은 단계가 적용됩니다.3356v2.1.309 이전에는 볼륨이 가득 찼거나 할당량을 모두 사용한 경우 Claude Code가 운영 체제의 오류 텍스트만 출력했습니다. 예를 들면 `ENOSPC: no space left on device, mkdir '/tmp/claude-501'`이며, 같은 단계가 적용됩니다.
3269 3357
3270### 디렉터리를 실제 위치로 확인할 수 없음3358### Directory couldn't be resolved to a real location
3271 3359
3272작업 디렉터리의 하위 디렉터리에 대해 `/add-dir`을 실행했지만 Claude Code가 해당 디렉터리의 실제 위치를 확인할 수 없었습니다.3360작업 디렉터리의 하위 디렉터리에 대해 `/add-dir`을 실행했는데, Claude Code가 해당 디렉터리를 실제 위치로 확인하지 못했습니다.
3273 3361
3274작업 디렉터리의 하위 디렉터리에는 이미 파일 접근 권한이 있으므로 `/add-dir`은 해당 디렉터리의 스킬, 명령, 에이전트만 로드합니다. 이를 로드하기 전에 Claude Code는 심볼릭 링크를 모두 확인한 디렉터리의 실제 위치가 작업 디렉터리 내부에 있는지 검사합니다. Claude Code가 그 위치를 확인할 수 없으면 아무것도 로드하지 않고 다음 메시지를 표시합니다:3362작업 디렉터리의 하위 디렉터리에는 이미 파일 접근 권한이 있으므로 `/add-dir`은 해당 디렉터리의 스킬, 명령, 에이전트만 불러옵니다. 이를 불러오기 전에 Claude Code는 심볼릭 링크를 모두 해석한 디렉터리의 실제 위치가 작업 디렉터리 안에 있는지 확인합니다. Claude Code가 해당 위치를 확인할 수 없으면 아무것도 불러오지 않고 다음 메시지를 표시합니다.
3275 3363
3276```text theme={null}3364```text theme={null}
3277packages/app couldn't be resolved to a real location, so its skills, commands, and agents weren't loaded. Check that it is a directory inside the working directory and try again.3365packages/app couldn't be resolved to a real location, so its skills, commands, and agents weren't loaded. Check that it is a directory inside the working directory and try again.
3279 3367
3280**해결 방법:**3368**해결 방법:**
3281 3369
3282* 경로가 작업 디렉터리 내부의 실제 디렉터리를 가리키는지 확인한 다음 `/add-dir`을 다시 실행합니다3370* 경로가 작업 디렉터리 안의 실제 디렉터리를 가리키는지 확인한 다음 `/add-dir`을 다시 실행합니다
3283* 이 메시지는 파일 접근 권한을 변경하지 않으며, 디렉터리의 `.claude/` 콘텐츠가 로드되지 않았음을 알릴 뿐입니다3371* 이 메시지는 파일 접근 권한을 변경하지 않으며, 디렉터리의 `.claude/` 콘텐츠가 로드되지 않았다는 사실만 알립니다
3284 3372
3285v2.1.261 이전에는 작업 디렉터리가 `/net/<host>` 자동 마운트에 있을 때 모든 `/add-dir <subdirectory>`에 대해 이 메시지가 표시되었습니다. Claude Code는 설계상 그러한 위치의 경로를 확인하지 않으므로, 디렉터리에 문제가 없었고 재시도해도 소용이 없었습니다.3373v2.1.261 이전에는 작업 디렉터리가 `/net/<host>` 자동 마운트에 있을 때 모든 `/add-dir <subdirectory>`에 대해 이 메시지가 나타났습니다. 해당 위치에서는 Claude Code가 설계상 경로 확인을 하지 않으므로, 디렉터리에는 문제가 없었고 재시도해도 소용이 없었습니다.
3286 3374
3287### Remote Control 시작 시 워크스페이스를 신뢰하지 않음3375### Workspace not trusted when starting Remote Control
3288 3376
3289> [!NOTE]3377> [!NOTE]
3290>3378>
3291> `claude ultrareview`가 `Error: Workspace not trusted`를 출력한 경우 대신 [claude ultrareview 실행 시 워크스페이스를 신뢰하지 않음](#workspace-not-trusted-when-running-claude-ultrareview)을 참조하세요.3379> `claude ultrareview`가 `Error: Workspace not trusted`를 출력했다면 대신 [claude ultrareview 실행 시 Workspace not trusted](#workspace-not-trusted-when-running-claude-ultrareview)를 참조하세요.
3292 3380
3293신뢰하지 않은 디렉터리에서 `claude remote-control` 또는 그 별칭인 `claude rc`로 [Remote Control](https://code.claude.com/docs/ko/remote-control.md) 서버 모드를 시작했지만, 명령이 디렉터리를 신뢰할지 물을 수 없었습니다. 예를 들어 표준 입력이나 표준 출력 중 하나가 리디렉션되거나 파이프로 연결되어 터미널이 아닌 경우입니다. 명령은 종료 코드 1로 종료됩니다:3381신뢰하지 않은 디렉터리에서 `claude remote-control` 또는 별칭 `claude rc`로 [Remote Control](https://code.claude.com/docs/ko/remote-control.md) 서버 모드를 시작했는데, 명령이 해당 디렉터리를 신뢰할지 물어볼 수 없었습니다. 예를 들어 표준 입력이나 표준 출력 중 하나가 리디렉션되거나 파이프로 연결되어 터미널이 아닌 경우입니다. 명령은 종료 코드 1로 종료됩니다.
3294 3382
3295```text theme={null}3383```text theme={null}
3296Error: Workspace not trusted. Please run `claude` in /Users/you/project first to review and accept the workspace trust dialog.3384Error: Workspace not trusted. Please run `claude` in /Users/you/project first to review and accept the workspace trust dialog.
3297```3385```
3298 3386
3299`Error: Workspace not trusted.`로 시작하는 두 가지 변형은 디렉터리를 신뢰하면 켜지는 항목을 표시하기에 너무 작은 터미널이나 크기를 보고하지 않는 터미널에서도 나타납니다. 창을 키우거나 일반 터미널 창으로 전환한 다음 `claude rc`를 다시 실행합니다.3387역시 `Error: Workspace not trusted.`로 시작하는 두 가지 변형은 디렉터리를 신뢰했을 때 켜지는 항목을 표시하기에 터미널이 너무 작거나 터미널이 크기를 보고하지 않은 경우에 나타납니다. 창을 키우거나 일반 터미널 창으로 전환한 다음 `claude rc`를 다시 실행합니다.
3300 3388
3301홈 디렉터리에서는 메시지가 다릅니다. 워크스페이스 신뢰 대화 상자는 홈 디렉터리에 대한 신뢰를 절대 저장하지 않으므로, 그곳에서 신뢰를 수락해도 이 검사를 통과할 수 없기 때문입니다. v2.1.214 이전에는 홈 디렉터리에서 위의 메시지가 표시되었으며, 그 조언은 홈 디렉터리에서 성공할 수 없었습니다.3389홈 디렉터리에서는 메시지가 다릅니다. 워크스페이스 신뢰 대화 상자는 홈 디렉터리에 대한 신뢰를 절대 저장하지 않으므로, 그곳에서 수락해도 이 검사를 통과할 수 없기 때문입니다. v2.1.214 이전에는 홈 디렉터리에서도 위의 메시지가 표시되었는데, 그 안내는 홈 디렉터리에서는 성공할 수 없습니다.
3302 3390
3303```text theme={null}3391```text theme={null}
3304Error: Workspace not trusted. /Users/you is your home directory, and for security home-directory trust is never saved, so running `claude` here first won't help. Run `claude rc` from a project directory instead (run `claude` there once to accept the trust dialog).3392Error: Workspace not trusted. /Users/you is your home directory, and for security home-directory trust is never saved, so running `claude` here first won't help. Run `claude rc` from a project directory instead (run `claude` there once to accept the trust dialog).
3305```3393```
3306 3394
3307[`Trust <directory>?` 질문](https://code.claude.com/docs/ko/remote-control#requirements)에 `n`으로 답하거나 Enter를 누르면, 명령은 디렉터리 이름이 포함된 `Remote Control did not start` 메시지를 출력하고 종료 코드 1로 종료됩니다. `claude rc`를 다시 실행하여 `y`로 답합니다.3395[`Trust <directory>?` 질문](https://code.claude.com/docs/ko/remote-control#requirements)에 `n`으로 답하거나 Enter를 누르면, 명령은 디렉터리 이름이 포함된 `Remote Control did not start` 메시지를 출력하고 종료 코드 1로 종료됩니다. `y`로 답하려면 `claude rc`를 다시 실행합니다.
3308 3396
3309**해결 방법:**3397**해결 방법:**
3310 3398
3311* 먼저 터미널에서 디렉터리를 신뢰합니다. 그곳에서 `claude rc`를 실행하고 `y`로 답하거나, `claude`를 실행하고 [워크스페이스 신뢰 대화 상자](https://code.claude.com/docs/ko/permissions.md#project-allow-rules-and-workspace-trust)를 수락한 다음 원래 명령을 다시 실행합니다3399* 먼저 터미널에서 디렉터리를 신뢰합니다. 그곳에서 `claude rc`를 실행하고 `y`로 답하거나, `claude`를 실행하고 [워크스페이스 신뢰 대화 상자](https://code.claude.com/docs/ko/permissions.md#project-allow-rules-and-workspace-trust)를 수락한 다음 원래 명령을 다시 실행합니다
3312* 홈 디렉터리에 있다면 프로젝트 디렉터리로 이동하여 그곳에서 Remote Control을 시작합니다3400* 홈 디렉터리에 있다면 프로젝트 디렉터리로 이동해 그곳에서 Remote Control을 시작합니다
3313 3401
3314v2.1.284 이전에는 터미널에서도 명령이 묻지 않았습니다.3402v2.1.284 이전에는 터미널에서도 명령이 묻지 않았습니다.
3315 3403
3316### claude ultrareview 실행 시 워크스페이스를 신뢰하지 않음3404### claude ultrareview 실행 시 Workspace not trusted
3317 3405
3318신뢰하지 않은 폴더에서 [`claude ultrareview`](https://code.claude.com/docs/ko/ultrareview#trust-the-folder-before-the-review-runs)가 폴더를 신뢰하는지 물어볼 수 없으면, 리뷰가 시작되기 전에 실행이 종료 코드 1로 종료됩니다:3406신뢰하지 않은 폴더에서 [`claude ultrareview`](https://code.claude.com/docs/ko/ultrareview#trust-the-folder-before-the-review-runs)가 해당 폴더를 신뢰하는지 물어볼 수 없으면, 리뷰가 시작되기 전에 실행이 종료 코드 1로 종료됩니다.
3319 3407
3320```text theme={null}3408```text theme={null}
3321Error: Workspace not trusted. Please run `claude` in /Users/you/project first to review and accept the workspace trust dialog. Or, in a script or CI job, pass `--trust-workspace` to trust the folder for this run only.3409Error: Workspace not trusted. Please run `claude` in /Users/you/project first to review and accept the workspace trust dialog. Or, in a script or CI job, pass `--trust-workspace` to trust the folder for this run only.
3322```3410```
3323 3411
3324예를 들어 표준 입력이나 표준 출력이 터미널이 아니면 하위 명령이 물어볼 수 없습니다. `claude ultrareview --json > findings.json`처럼 출력을 파일로 보내면 표준 출력이 터미널이 아니게 됩니다.3412예를 들어 하위 명령은 표준 입력이나 표준 출력이 터미널이 아니면 물어볼 수 없습니다. `claude ultrareview --json > findings.json`처럼 출력을 파일로 보내면 표준 출력은 터미널이 아닙니다.
3325 3413
3326**해결 방법:**3414**해결 방법:**
3327 3415
3328* 스크립트나 CI 작업에서는 `--trust-workspace`를 추가하여 해당 실행에 한해 폴더를 신뢰합니다: `claude ultrareview --trust-workspace`. 이 플래그를 추가하면 git과 Claude Code가 폴더의 git 구성과 프로젝트 설정에 지정된 프로그램을 실행할 수 있으므로, 신뢰하는 코드에만 추가합니다. 코드를 신뢰하지 않는 풀 리퀘스트의 경우 [신뢰하는 브랜치에서 리뷰를 실행](https://code.claude.com/docs/ko/ultrareview.md#trust-the-folder-before-the-review-runs)합니다.3416* 스크립트나 CI 작업에서는 `--trust-workspace`를 추가해 해당 실행에 대해 폴더를 신뢰합니다: `claude ultrareview --trust-workspace`. 이 경우 git과 Claude Code가 폴더의 git 구성과 프로젝트 설정에 지정된 프로그램을 실행할 수 있으므로, 신뢰하는 코드에 대해서만 추가합니다. 코드를 신뢰하지 않는 풀 리퀘스트라면 [신뢰하는 브랜치에서 리뷰를 실행](https://code.claude.com/docs/ko/ultrareview.md#trust-the-folder-before-the-review-runs)합니다.
3329* 자신의 컴퓨터에서는 해당 폴더에서 `claude`를 실행하고 [워크스페이스 신뢰 대화 상자](https://code.claude.com/docs/ko/permissions.md#project-allow-rules-and-workspace-trust)를 수락한 다음 원래 명령을 다시 실행합니다3417* 자신의 컴퓨터에서는 해당 폴더에서 `claude`를 실행하고 [워크스페이스 신뢰 대화 상자](https://code.claude.com/docs/ko/permissions.md#project-allow-rules-and-workspace-trust)를 수락한 다음 원래 명령을 다시 실행합니다
3330 3418
3331`claude ultrareview`의 다음 각 메시지는 리뷰가 시작되지 않았고 종료 코드가 1이라는 의미입니다:3419`claude ultrareview`에서 나오는 다음 메시지는 모두 리뷰가 시작되지 않았으며 종료 코드가 1이라는 의미입니다.
3332 3420
3333* **`Error: Workspace not trusted. This terminal ...`**: 터미널이 행과 열 수를 보고하지 않았거나 신뢰 질문과 경고를 표시할 수 없습니다. 터미널을 키우거나 크기를 보고하는 터미널을 사용한 다음 `claude ultrareview`를 다시 실행합니다. 홈 디렉터리 밖이라면 해당 폴더에서 `claude`를 한 번 실행하고 신뢰 대화 상자를 수락하여 이후 실행에서 묻지 않도록 할 수도 있습니다.3421* **`Error: Workspace not trusted. This terminal ...`**: 터미널이 행과 열 수를 보고하지 않았거나, 신뢰 질문과 경고를 표시할 공간이 부족합니다. 터미널을 키우거나 크기를 보고하는 터미널을 사용한 다음 `claude ultrareview`를 다시 실행합니다. 홈 디렉터리 외부라면 해당 폴더에서 `claude`를 한 번 실행하고 신뢰 대화 상자를 수락해 이후 실행에서 묻지 않도록 할 수도 있습니다.
3334* **`Error: Workspace not trusted. <folder> is your home directory`**: 홈 디렉터리에 대한 신뢰는 저장되지 않으므로, 먼저 그곳에서 `claude`를 실행해도 도움이 되지 않습니다. 대신 프로젝트 디렉터리에서 `claude`를 한 번 실행하여 신뢰 대화 상자를 수락한 후 그곳에서 `claude ultrareview`를 실행하거나, `--trust-workspace`를 추가합니다.3422* **`Error: Workspace not trusted. <folder> is your home directory`**: 홈 디렉터리에 대한 신뢰는 절대 저장되지 않으므로 그곳에서 먼저 `claude`를 실행해도 도움이 되지 않습니다. 대신 프로젝트 디렉터리에서 `claude`를 한 번 실행해 신뢰 대화 상자를 수락한 후 그곳에서 `claude ultrareview`를 실행하거나, `--trust-workspace`를 추가합니다.
3335* **`No answer in time.` 뒤에 `Error: Workspace not trusted`**: `Trust <folder>? [y/N]` 질문에 5분 동안 답하지 않았습니다. `claude ultrareview`를 다시 실행하고 답합니다.3423* **`No answer in time.` 뒤에 `Error: Workspace not trusted`**: `Trust <folder>? [y/N]` 질문에 5분 동안 응답이 없었습니다. `claude ultrareview`를 다시 실행하고 질문에 답합니다.
3336* **`Ultrareview did not start: <folder> is not trusted`**: `n`으로 답하거나 Enter를 누르는 등 `Trust <folder>? [y/N]` 질문을 거절했습니다. 리뷰를 시작하려면 `claude ultrareview`를 다시 실행하고 `y`로 답합니다.3424* **`Ultrareview did not start: <folder> is not trusted`**: `n`으로 답하거나 Enter를 누르는 등 `Trust <folder>? [y/N]` 질문에서 거절했습니다. 리뷰를 시작하려면 `claude ultrareview`를 다시 실행하고 `y`로 답합니다.
3337* **``Ultrareview did not start: `--trust-workspace` takes no value``**: `--trust-workspace` 뒤에 PR 번호나 `false`처럼 플래그가 아닌 것이 왔습니다. 폴더를 신뢰하지 않는다면 플래그를 빼세요. 이번 실행에 대해 신뢰하려면 PR 번호나 기준 브랜치를 플래그 앞에 둡니다: `claude ultrareview 1234 --trust-workspace`.3425* **``Ultrareview did not start: `--trust-workspace` takes no value``**: `--trust-workspace` 뒤에 PR 번호나 `false`처럼 플래그가 아닌 값이 왔습니다. 폴더를 신뢰하지 않는다면 플래그를 빼고 실행합니다. 이번 실행에 대해 신뢰하려면 PR 번호나 기준 브랜치를 플래그 앞에 둡니다: `claude ultrareview 1234 --trust-workspace`.
3338 3426
3339v2.1.309 이전에는 `claude ultrareview`가 `--trust-workspace`를 받지 않았습니다.3427v2.1.309 이전에는 `claude ultrareview`가 `--trust-workspace`를 받지 않았습니다.
3340 3428
3341### Remote Control이 시작하는 세션으로 전달되지 않음3429### Not carried over to the sessions Remote Control starts
3342 3430
3343`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는 대신 플래그 이름을 표시하며 시작을 거부합니다:3431`remote-control` 동사 앞에 Remote Control이 시작하는 세션을 제한하거나 구성하는 전역 `claude` 플래그(예: `--settings`, `--setting-sources`, `--permission-mode`, `--disallowed-tools`, `--mcp-config`)를 넣어 [Remote Control](https://code.claude.com/docs/ko/remote-control.md)을 시작했습니다. 동사 앞에 둔 플래그는 해당 세션에 전달되지 않습니다. 대신 Claude Code는 해당 플래그의 이름을 표시하며 시작을 거부합니다.
3344 3432
3345```text theme={null}3433```text theme={null}
3346Error: `--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`).3434Error: `--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`).
3347```3435```
3348 3436
3349`--verbose`, `--model`, 또는 래퍼가 주입한 `--session-id`나 `--plugin-dir`처럼 제외해도 무해한 전역 플래그는 거부하지 않습니다. Claude Code는 이를 무시하고 Remote Control을 시작합니다.3437`--verbose`, `--model`, 래퍼가 주입한 `--session-id`나 `--plugin-dir`처럼 버려도 무해한 전역 플래그는 거부하지 않습니다. Claude Code는 이를 무시하고 Remote Control이 시작됩니다.
3350 3438
3351Claude Code는 아직 무해한 것으로 인식하지 못한 전역 플래그에 대해서도 시작을 거부하므로, 새 릴리스에서 추가된 플래그가 이후 릴리스에서 무해한 것으로 표시될 때까지 이 메시지에 나타날 수 있습니다.3439Claude Code는 아직 무해하다고 인식하지 않은 전역 플래그에 대해서도 시작을 거부하므로, 최신 릴리스에서 추가된 플래그는 이후 릴리스에서 무해한 것으로 표시될 때까지 이 메시지에 나타날 수 있습니다.
3352 3440
3353**해결 방법:**3441**해결 방법:**
3354 3442
3355* 동사 앞에서 플래그를 제거하고 [Remote Control 자체 옵션](https://code.claude.com/docs/ko/remote-control.md#start-a-remote-control-session)을 동사 뒤에 전달합니다. `claude remote-control --help`로 옵션 목록을 확인할 수 있습니다3443* 동사 앞에서 플래그를 제거하고 [Remote Control 자체 옵션](https://code.claude.com/docs/ko/remote-control.md#start-a-remote-control-session)은 동사 뒤에 전달합니다. `claude remote-control --help`에서 옵션 목록을 확인할 수 있습니다
3356* 거부된 플래그가 `--permission-mode`인 경우 `claude remote-control --permission-mode <mode>`를 실행하여 Remote Control이 시작하는 세션의 권한 모드를 설정합니다3444* 거부된 플래그가 `--permission-mode`인 경우 `claude remote-control --permission-mode <mode>`를 실행해 Remote Control이 시작하는 세션의 권한 모드를 설정합니다
3357 3445
3358v2.1.248 이전에는 전역 플래그가 먼저 오면 `claude remote-control`이 자체 플래그를 받지 않았으며, 명령이 `unknown option` 오류로 실패했습니다.3446v2.1.248 이전에는 전역 플래그가 먼저 오면 `claude remote-control`이 자체 플래그를 받지 않았고, 명령이 `unknown option` 오류로 실패했습니다.
3359 3447
3360### `--sandbox` or `--no-sandbox` is not supported by claude remote-control3448### `--sandbox` or `--no-sandbox` is not supported by claude remote-control
3361 3449
3362이 오류는 [Remote Control](https://code.claude.com/docs/ko/remote-control.md) 서버를 시작하는 명령이 `remote-control` 뒤에 `--sandbox` 또는 `--no-sandbox`를 전달하는데, `claude remote-control`이 두 플래그를 모두 받지 않는다는 뜻입니다. 서버는 시작하지 않고 코드 1로 종료됩니다:3450이 오류는 [Remote Control](https://code.claude.com/docs/ko/remote-control.md) 서버를 시작하는 명령이 `remote-control` 뒤에 `--sandbox` 또는 `--no-sandbox`를 전달하는데, `claude remote-control`이 두 플래그를 모두 받지 않는다는 의미입니다. 서버는 시작하지 않고 종료 코드 1로 종료됩니다.
3363 3451
3364```text theme={null}3452```text theme={null}
3365Error: --sandbox is not supported by claude remote-control. The flag had no effect and was removed. To sandbox sessions, set sandbox.enabled to true in settings.3453Error: --sandbox is not supported by claude remote-control. The flag had no effect and was removed. To sandbox sessions, set sandbox.enabled to true in settings.
3371* 서버를 대신 시작하는 스크립트나 서비스 정의를 포함해 명령에서 플래그를 제거한 다음 다시 실행합니다3459* 서버를 대신 시작하는 스크립트나 서비스 정의를 포함해 명령에서 플래그를 제거한 다음 다시 실행합니다
3372* 서버가 시작하는 세션을 샌드박스에서 실행하려면 [설정 파일](https://code.claude.com/docs/ko/settings.md#where-settings-live)에서 [`sandbox.enabled`](https://code.claude.com/docs/ko/settings-reference#sandbox-enabled)를 `true`로 설정해 [샌드박싱](https://code.claude.com/docs/ko/sandboxing.md)을 켭니다3460* 서버가 시작하는 세션을 샌드박스에서 실행하려면 [설정 파일](https://code.claude.com/docs/ko/settings.md#where-settings-live)에서 [`sandbox.enabled`](https://code.claude.com/docs/ko/settings-reference#sandbox-enabled)를 `true`로 설정해 [샌드박싱](https://code.claude.com/docs/ko/sandboxing.md)을 켭니다
3373 3461
3374두 플래그 모두 v2.1.300에서 `claude remote-control`에서 제거되었으므로, 이전 버전용으로 작성된 명령에는 여전히 플래그가 포함되어 있을 수 있습니다.3462두 플래그는 v2.1.300에서 `claude remote-control`에서 제거되었으므로, 이전 버전용으로 작성된 명령에는 여전히 플래그가 포함되어 있을 수 있습니다.
3375 3463
3376### 이 빌드에서는 아직 claude import를 사용할 수 없음3464### claude import is not yet available in this build
3377 3465
3378[`claude import`](https://code.claude.com/docs/ko/cli-reference#cli-commands)를 실행했지만 Claude Code가 가져오기 흐름이 꺼져 있음을 확인했으므로, 명령이 가져오기를 시작하지 않고 종료 코드 1로 종료됩니다. v2.1.222 이전에는 가져오기 흐름이 꺼진 빌드에서 `import`를 프롬프트로 처리하여 이 메시지를 출력하는 대신 대화형 세션을 시작했습니다.3466[`claude import`](https://code.claude.com/docs/ko/cli-reference#cli-commands)를 실행했는데 Claude Code가 가져오기 흐름이 꺼져 있음을 확인했으므로, 명령이 가져오기를 시작하지 않고 종료 코드 1로 종료됩니다. v2.1.222 이전에는 가져오기 흐름이 꺼진 빌드에서 `import`를 프롬프트로 처리해 이 메시지를 출력하는 대신 대화형 세션을 시작했습니다.
3379 3467
3380```text theme={null}3468```text theme={null}
3381`claude import` is not yet available in this build. Run `claude` and use /mcp or edit ~/.claude/settings.json directly.3469`claude import` is not yet available in this build. Run `claude` and use /mcp or edit ~/.claude/settings.json directly.
3382```3470```
3383 3471
3384Claude Code는 Anthropic에서 가져와 디스크에 캐시하는 기능 플래그를 통해 `claude import`를 켭니다. 이 메시지는 캐시된 값이 꺼져 있음을 의미합니다. 원인은 대개 다음 중 하나입니다:3472Claude Code는 Anthropic에서 가져와 디스크에 캐시하는 기능 플래그를 통해 `claude import`를 켭니다. 이 메시지는 캐시된 값이 꺼져 있다는 의미입니다. 원인은 대개 다음 중 하나입니다.
3385 3473
3386* 설치 후 아직 세션을 시작하지 않아 Claude Code가 플래그를 가져오지 못했습니다. 기능을 사용할 수 있는 경우에도 첫 번째 `claude import`에서 이 메시지가 출력될 수 있습니다.3474* 설치 후 아직 세션을 시작하지 않아 Claude Code가 플래그를 가져오지 않았습니다. 기능을 사용할 수 있더라도 첫 번째 `claude import`에서 이 메시지가 출력될 수 있습니다.
3387* Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, Claude Platform on AWS 또는 [Claude apps 게이트웨이](https://code.claude.com/docs/ko/claude-apps-gateway#availability-and-limitations)를 통해 Claude Code를 사용합니다. 이러한 세션에서는 Claude Code가 기능 플래그를 가져오지 않으므로 `claude import`를 계속 사용할 수 없습니다.3475* Amazon Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry, Claude Platform on AWS 또는 [Claude apps 게이트웨이](https://code.claude.com/docs/ko/claude-apps-gateway#availability-and-limitations)를 통해 Claude Code를 사용하고 있습니다. 이러한 세션에서는 Claude Code가 기능 플래그를 가져오지 않으므로 `claude import`를 계속 사용할 수 없습니다.
3388* 기능 플래그 가져오기를 끄는 `DISABLE_TELEMETRY`, `DO_NOT_TRACK`, `DISABLE_GROWTHBOOK` 또는 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](https://code.claude.com/docs/ko/env-vars)를 설정했으므로 `claude import`를 계속 사용할 수 없습니다.3476* 기능 플래그 가져오기를 끄는 `DISABLE_TELEMETRY`, `DO_NOT_TRACK`, `DISABLE_GROWTHBOOK` 또는 [`CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`](https://code.claude.com/docs/ko/env-vars)를 설정했으므로 `claude import`를 계속 사용할 수 없습니다.
3389 3477
3390**해결 방법:**3478**해결 방법:**
3391 3479
3392* 새로 설치한 경우 `claude`를 시작하고 세션이 로드될 때까지 기다린 다음 종료하고 `claude import`를 다시 실행합니다3480* 새로 설치한 경우 `claude`를 시작하고 세션이 로드될 때까지 기다린 다음 종료하고 `claude import`를 다시 실행합니다
3393* 기능 플래그 가져오기가 계속 꺼져 있는 환경에서는 구성을 직접 설정합니다. [`claude mcp add`](https://code.claude.com/docs/ko/mcp#installing-mcp-servers)로 MCP 서버를 추가하고, 옮기려는 [`CLAUDE.md` 파일](https://code.claude.com/docs/ko/memory#how-claude-md-files-load), [스킬과 명령](https://code.claude.com/docs/ko/skills.md#where-skills-live), [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md#choose-the-subagent-scope)를 만듭니다. 메시지에는 `~/.claude/settings.json`도 언급됩니다. `claude import`가 옮기는 구성 중 해당 파일에는 [권한 모드](https://code.claude.com/docs/ko/settings-reference.md#permission-settings)만 들어 있으며, Claude Code는 이 파일에서 MCP 서버를 읽지 않습니다.3481* 기능 플래그 가져오기가 계속 꺼져 있는 환경에서는 직접 구성을 설정합니다. [`claude mcp add`](https://code.claude.com/docs/ko/mcp#installing-mcp-servers)로 MCP 서버를 추가하고, 옮기려는 [`CLAUDE.md` 파일](https://code.claude.com/docs/ko/memory#how-claude-md-files-load), [스킬과 명령](https://code.claude.com/docs/ko/skills.md#where-skills-live), [서브에이전트](https://code.claude.com/docs/ko/sub-agents.md#choose-the-subagent-scope)를 만듭니다. 메시지에는 `~/.claude/settings.json`도 언급되어 있습니다. `claude import`가 옮기는 구성 중 이 파일에 담기는 것은 [권한 모드](https://code.claude.com/docs/ko/settings-reference.md#permission-settings)뿐이며, Claude Code는 이 파일에서 MCP 서버를 읽지 않습니다.
3394 3482
3395### Claude Code 구성을 읽을 수 없음3483### Could not read Claude Code config
3396 3484
3397Claude Code가 계정 세부 정보와 프로젝트별 상태를 저장하는 파일인 `~/.claude.json`을 파싱할 수 없는 상태에서 [`claude import`](https://code.claude.com/docs/ko/cli-reference#cli-commands)를 실행했습니다. 이 하위 명령은 가용성을 확인하기 위해 해당 파일을 읽지만 대화형 세션이 표시하는 복구 대화 상자를 표시하지 않으므로 종료 코드 1로 종료됩니다. v2.1.222 이전에는 읽을 수 없는 설정 파일이 있을 때 `claude import`가 대화형 세션을 시작했으며, 그 세션의 복구 대화 상자가 파일을 처리했습니다.3485Claude Code가 계정 정보와 프로젝트별 상태를 저장하는 파일인 `~/.claude.json`을 구문 분석할 수 없는 상태에서 [`claude import`](https://code.claude.com/docs/ko/cli-reference#cli-commands)를 실행했습니다. 하위 명령은 사용 가능 여부를 확인하기 위해 이 파일을 읽지만 대화형 세션이 표시하는 복구 대화 상자는 표시하지 않으므로 종료 코드 1로 종료됩니다. v2.1.222 이전에는 설정 파일을 읽을 수 없을 때 `claude import`가 대화형 세션을 시작했고, 그 세션의 복구 대화 상자가 파일을 처리했습니다.
3398 3486
3399```text theme={null}3487```text theme={null}
3400Could not read Claude Code config — run `claude` with no arguments to recover it.3488Could not read Claude Code config — run `claude` with no arguments to recover it.
3402 3490
3403**해결 방법:**3491**해결 방법:**
3404 3492
3405* 인수 없이 `claude`를 실행합니다. Claude Code가 잘못된 파일을 감지하고 재설정을 제안합니다. 그런 다음 `claude import`를 다시 실행합니다.3493* 인수 없이 `claude`를 실행합니다. Claude Code가 잘못된 파일을 감지하고 초기화를 제안합니다. 그런 다음 `claude import`를 다시 실행합니다.
3406* 직접 수정한 내용을 유지하려면 대신 편집기에서 `~/.claude.json`의 JSON 구문을 수정한 다음 `claude import`를 다시 실행합니다3494* 직접 편집한 내용을 유지하려면 대신 편집기에서 `~/.claude.json`의 JSON 구문을 수정한 다음 `claude import`를 다시 실행합니다
3407 3495
3408### Claude Desktop에서 서버를 가져올 수 없음3496### Could not import a server from Claude Desktop
3409 3497
3410Claude Code가 `claude mcp add-from-claude-desktop`에서 선택한 서버 중 하나를 추가할 수 없었습니다. 명령은 선택한 다른 서버는 계속 가져오며, 추가할 수 없었던 서버마다 한 줄씩 출력합니다. v2.1.205 이전에는 처음 실패한 서버에서 가져오기가 중단되었습니다.3498Claude Code가 `claude mcp add-from-claude-desktop`에서 선택한 서버 중 하나를 추가하지 못했습니다. 명령은 선택한 다른 서버를 계속 가져오며, 추가하지 못한 서버마다 한 줄씩 출력합니다. v2.1.205 이전에는 처음 실패한 서버에서 가져오기가 중단되었습니다.
3411 3499
3412```text theme={null}3500```text theme={null}
3413Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.3501Could not import my server: Invalid name my server. Names can only contain letters, numbers, hyphens, and underscores.
3414```3502```
3415 3503
3416서버 이름 뒤의 텍스트가 사유입니다. 가장 흔한 사유는 이름 검사입니다. Claude Desktop은 서버 이름에 공백이나 마침표 같은 문자를 허용하지만, `claude mcp`는 문자, 숫자, 하이픈, 밑줄로 제한합니다. 그 밖의 사유로는 검증에 실패한 서버 구성과 조직의 [MCP 정책](https://code.claude.com/docs/ko/managed-mcp.md)에 의해 차단된 서버가 있습니다.3504서버 이름 뒤의 텍스트가 사유입니다. 가장 흔한 사유는 이름 검사입니다. Claude Desktop은 서버 이름에 공백이나 마침표 같은 문자를 허용하지만 `claude mcp`는 문자, 숫자, 하이픈, 밑줄로 제한합니다. 그 밖의 사유로는 검증에 실패한 서버 구성과 조직의 [MCP 정책](https://code.claude.com/docs/ko/managed-mcp.md)에 의해 차단된 서버가 있습니다.
3417 3505
3418**해결 방법:**3506**해결 방법:**
3419 3507
3420* `claude_desktop_config.json`에서 서버 이름을 문자, 숫자, 하이픈, 밑줄만 사용하도록 변경한 다음 `claude mcp add-from-claude-desktop`을 다시 실행합니다3508* `claude_desktop_config.json`에서 서버 이름을 문자, 숫자, 하이픈, 밑줄만 사용하도록 변경한 다음 `claude mcp add-from-claude-desktop`을 다시 실행합니다
3421* 유효한 이름으로 `claude mcp add` 또는 `claude mcp add-json`을 사용해 해당 서버를 직접 추가합니다. [Claude Desktop에서 MCP 서버 가져오기](https://code.claude.com/docs/ko/mcp.md#import-mcp-servers-from-claude-desktop)를 참조하십시오.3509* 유효한 이름으로 `claude mcp add` 또는 `claude mcp add-json`을 사용해 해당 서버를 직접 추가합니다. [Claude Desktop에서 MCP 서버 가져오기](https://code.claude.com/docs/ko/mcp.md#import-mcp-servers-from-claude-desktop)를 참조하세요.
3422 3510
3423### managed 범위에 MCP 서버를 추가할 수 없음3511### Cannot add MCP server to the managed scope
3424 3512
3425`--scope managed`와 함께 `claude mcp add` 또는 `claude mcp add-json`을 실행했습니다. 이 범위에는 조직이 [`managedMcpServers`](https://code.claude.com/docs/ko/settings-reference#managedmcpservers) 관리형 설정을 통해 제공하는 서버가 들어 있습니다. Claude Code는 관리형 설정에서만 이를 읽으므로 명령이 해당 범위에 서버를 쓸 수 없습니다.3513`--scope managed`로 `claude mcp add` 또는 `claude mcp add-json`을 실행했습니다. 이 범위는 조직이 [`managedMcpServers`](https://code.claude.com/docs/ko/settings-reference#managedmcpservers) 관리형 설정을 통해 제공하는 서버를 담습니다. Claude Code는 이를 관리형 설정에서만 읽으므로 명령이 이 범위에 서버를 기록할 수 없습니다.
3426 3514
3427```text theme={null}3515```text theme={null}
3428Cannot add MCP server to scope: managed3516Cannot add MCP server to scope: managed
3430 3518
3431**해결 방법:**3519**해결 방법:**
3432 3520
3433* 쓸 수 있는 범위(`local`, `user` 또는 `project`)에 서버를 추가합니다. `--scope`가 없으면 명령은 `local`을 사용합니다. [MCP 설치 범위](https://code.claude.com/docs/ko/mcp.md#mcp-installation-scopes)를 참조하십시오3521* 기록할 수 있는 범위인 `local`, `user`, `project`에 서버를 추가합니다. `--scope`가 없으면 명령은 `local`을 사용합니다. [MCP 설치 범위](https://code.claude.com/docs/ko/mcp.md#mcp-installation-scopes)를 참조하세요
3434* 조직의 모든 사용자에게 서버를 제공하려면 배포하는 관리형 설정의 [`managedMcpServers`](https://code.claude.com/docs/ko/settings-reference#managedmcpservers)에 추가합니다3522* 조직의 모든 사용자에게 서버를 제공하려면 배포하는 관리형 설정의 [`managedMcpServers`](https://code.claude.com/docs/ko/settings-reference#managedmcpservers)에 추가합니다
3435 3523
3436### 관리형 설정이 플러그인 서버만 허용할 때 MCP 서버를 추가할 수 없음3524### 관리형 설정이 플러그인 서버만 허용하는 경우 MCP 서버를 추가할 수 없음
3437 3525
3438조직의 관리형 설정이 [`strictPluginOnlyCustomization`](https://code.claude.com/docs/ko/settings-reference#strictpluginonlycustomization)을 `true` 또는 `mcp`가 포함된 목록으로 설정한 상태에서 `claude mcp add` 또는 `claude mcp add-json`을 실행했습니다. 이 설정이 있으면 Claude Code는 `~/.claude.json`이나 `.mcp.json`에서 MCP 서버를 로드하지 않으므로, 명령은 절대 로드되지 않을 서버를 저장하는 대신 종료 코드 1로 종료됩니다:3526조직의 관리형 설정이 [`strictPluginOnlyCustomization`](https://code.claude.com/docs/ko/settings-reference#strictpluginonlycustomization)을 `true` 또는 `mcp`가 포함된 목록으로 설정한 상태에서 `claude mcp add` 또는 `claude mcp add-json`을 실행했습니다. 이 설정이 있으면 Claude Code는 `~/.claude.json`이나 `.mcp.json`에서 MCP 서버를 로드하지 않으므로, 명령은 절대 로드되지 않을 서버를 저장하는 대신 종료 코드 1로 종료됩니다.
3439 3527
3440```text theme={null}3528```text theme={null}
3441Cannot add MCP server: your organization's managed settings allow only MCP servers that plugins provide. Install a plugin that provides this server, or ask your administrator to make it available.3529Cannot add MCP server: your organization's managed settings allow only MCP servers that plugins provide. Install a plugin that provides this server, or ask your administrator to make it available.
3442```3530```
3443 3531
3444`claude mcp add-from-claude-desktop`은 선택한 각 서버를 가져오지 않은 것으로 보고하며, 이 메시지를 사유로 표시합니다. [`/import`](https://code.claude.com/docs/ko/commands#all-commands)는 추가하려는 각 MCP 서버에 대해 이 메시지를 보고하고, 찾은 다른 항목은 계속 가져옵니다.3532`claude mcp add-from-claude-desktop`은 선택한 각 서버를 가져오지 못한 것으로 보고하며 이 메시지를 사유로 표시합니다. [`/import`](https://code.claude.com/docs/ko/commands#all-commands)는 추가하려는 각 MCP 서버에 대해 이 메시지를 보고하고, 찾은 다른 항목은 계속 가져옵니다.
3445 3533
3446v2.1.284 이전에는 이러한 명령이 서버를 저장하고 성공을 보고했지만 서버는 로드되지 않았습니다.3534v2.1.284 이전에는 이 명령들이 서버를 저장하고 성공을 보고했지만, 서버는 절대 로드되지 않았습니다.
3447 3535
3448**해결 방법:**3536**해결 방법:**
3449 3537
3450* 해당 서버를 제공하는 [플러그인](https://code.claude.com/docs/ko/plugins/install.md)을 설치합니다3538* 해당 서버를 제공하는 [플러그인](https://code.claude.com/docs/ko/plugins/install.md)을 설치합니다
3451* 관리자에게 서버를 [플러그인](https://code.claude.com/docs/ko/plugins/org.md)으로 배포하거나, 원격 HTTP 또는 SSE 서버인 경우 [`managedMcpServers`](https://code.claude.com/docs/ko/settings-reference#managedmcpservers)를 통해 제공하도록 요청합니다3539* 관리자에게 [플러그인](https://code.claude.com/docs/ko/plugins/org.md)으로 서버를 배포하거나, 원격 HTTP 또는 SSE 서버인 경우 [`managedMcpServers`](https://code.claude.com/docs/ko/settings-reference#managedmcpservers)를 통해 제공해 달라고 요청합니다
3452 3540
3453### .mcp.json을 읽을 수 없음3541### Can't read .mcp.json
3454 3542
3455`--scope project`와 함께 실행한 `claude mcp add` 또는 `claude mcp add-json`, 또는 `claude mcp remove`처럼 프로젝트의 [`.mcp.json`](https://code.claude.com/docs/ko/mcp#project-scope)을 읽는 명령이 현재 디렉터리의 파일이 일반 파일이 아니거나 2MiB보다 크다는 것을 발견했기 때문에, 파일을 읽지 않고 이 오류와 함께 종료됩니다.3543`--scope project`를 사용한 `claude mcp add` 또는 `claude mcp add-json`, 또는 `claude mcp remove`처럼 프로젝트의 [`.mcp.json`](https://code.claude.com/docs/ko/mcp#project-scope)을 읽는 명령이 현재 디렉터리의 파일이 일반 파일이 아니거나 2 MiB보다 큰 것을 발견했으므로, 파일을 읽는 대신 이 오류와 함께 종료됩니다.
3456 3544
3457```text theme={null}3545```text theme={null}
3458Can't read .mcp.json: it isn't a regular file or is larger than 2097152 bytes. Fix or remove it, then run the command again.3546Can't read .mcp.json: it isn't a regular file or is larger than 2097152 bytes. Fix or remove it, then run the command again.
3459```3547```
3460 3548
3461v2.1.257 이전에는 `.mcp.json` 위치에 FIFO가 있으면 명령이 출력 없이 무한히 대기했고, `/dev/zero` 같은 장치 파일을 가리키는 심볼릭 링크가 있으면 프로세스가 종료될 때까지 메모리가 증가했습니다.3549v2.1.257 이전에는 `.mcp.json` 위치의 FIFO로 인해 명령이 출력 없이 무한정 대기했고, `/dev/zero` 같은 장치 파일에 대한 심볼릭 링크는 프로세스가 강제 종료될 때까지 메모리를 증가시켰습니다.
3462 3550
3463**해결 방법:**3551**해결 방법:**
3464 3552
3465* 현재 디렉터리의 `.mcp.json` 위치에 무엇이 있는지 확인합니다. [프로젝트 범위 형식](https://code.claude.com/docs/ko/mcp.md#project-scope)의 일반 JSON 파일로 교체하거나 삭제한 다음 명령을 다시 실행합니다.3553* 현재 디렉터리의 `.mcp.json` 위치에 무엇이 있는지 확인합니다. [프로젝트 범위 형식](https://code.claude.com/docs/ko/mcp.md#project-scope)의 일반 JSON 파일로 대체하거나 삭제한 다음 명령을 다시 실행합니다.
3466 3554
3467### MCP 서버가 저장되거나 제거되지 않음3555### MCP server was not saved or removed
3468 3556
3469`user` 또는 `local` [범위](https://code.claude.com/docs/ko/mcp.md#mcp-installation-scopes)의 서버에 대해 `claude mcp add`, `claude mcp add-json` 또는 `claude mcp remove`를 실행했습니다. 두 범위 모두 `~/.claude.json`에 저장되는데, 쓰기 후 Claude Code가 파일을 다시 읽었을 때 변경 사항이 파일에 없었습니다. 명령은 성공 메시지 대신 이 오류와 함께 종료됩니다.3557`user` 또는 `local` [범위](https://code.claude.com/docs/ko/mcp.md#mcp-installation-scopes)의 서버에 대해 `claude mcp add`, `claude mcp add-json` 또는 `claude mcp remove`를 실행했습니다. 두 범위 모두 `~/.claude.json`에 저장되는데, Claude Code가 기록 후 파일을 다시 읽었을 때 변경 사항이 없었습니다. 명령은 성공 줄 대신 이 오류와 함께 종료됩니다.
3470 3558
3471```text theme={null}3559```text theme={null}
3472MCP server "example" was not saved to /home/user/.claude.json. If that file is read-only or protected by a sandbox, make it writable or run the command outside the sandbox, then add the server again.3560MCP server "example" was not saved to /home/user/.claude.json. If that file is read-only or protected by a sandbox, make it writable or run the command outside the sandbox, then add the server again.
3474 3562
3475제거 후에는 메시지가 `was not removed from`으로 표시되고 `then remove the server again`으로 끝납니다. `local` 범위 서버의 경우 경로 뒤에 해당 항목이 속한 프로젝트 디렉터리가 `(local scope for /path/to/project)` 형식으로 표시됩니다.3563제거 후에는 메시지가 `was not removed from`으로 표시되고 `then remove the server again`으로 끝납니다. `local` 범위 서버의 경우 경로 뒤에 해당 항목이 속한 프로젝트 디렉터리가 `(local scope for /path/to/project)` 형식으로 표시됩니다.
3476 3564
3477v2.1.283 이전에는 변경 사항이 파일에 반영되지 않은 경우에도 `claude mcp add`, `claude mcp add-json`, `claude mcp remove`가 성공을 보고했습니다.3565v2.1.283 이전에는 변경 사항이 파일에 반영되지 않았어도 `claude mcp add`, `claude mcp add-json`, `claude mcp remove`가 성공을 보고했습니다.
3478 3566
3479**해결 방법:**3567**해결 방법:**
3480 3568
3481* 메시지에 표시된 파일을 쓰기 가능하게 만들거나 샌드박스 외부에서 명령을 실행한 다음, 같은 추가 또는 제거 명령을 다시 실행합니다.3569* 메시지에 표시된 파일을 쓰기 가능하게 만들거나 샌드박스 외부에서 명령을 실행한 다음, 같은 추가 또는 제거 명령을 다시 실행합니다.
3482 3570
3483### MCP 서버가 저장되거나 제거되지 않았을 수 있음3571### MCP server may not have been saved or removed
3484 3572
3485`user` 또는 `local` [범위](https://code.claude.com/docs/ko/mcp.md#mcp-installation-scopes)의 서버에 대해 `claude mcp add`, `claude mcp add-json` 또는 `claude mcp remove`를 실행했지만, Claude Code가 변경 사항을 확인하기 위해 `~/.claude.json`을 다시 읽을 수 없었습니다. 변경 사항이 디스크에 반영되었을 수도 있고 그렇지 않을 수도 있습니다. 괄호 안의 텍스트는 해당 읽기에서 발생한 오류입니다.3573`user` 또는 `local` [범위](https://code.claude.com/docs/ko/mcp.md#mcp-installation-scopes)의 서버에 대해 `claude mcp add`, `claude mcp add-json` 또는 `claude mcp remove`를 실행했는데, Claude Code가 변경 사항을 확인하기 위해 `~/.claude.json`을 다시 읽지 못했습니다. 변경 사항이 디스크에 반영되었을 수도 있고 아닐 수도 있습니다. 괄호 안의 텍스트는 해당 읽기에서 발생한 오류입니다.
3486 3574
3487```text theme={null}3575```text theme={null}
3488MCP server "example" may not have been saved: /home/user/.claude.json could not be read to confirm the change (EACCES: permission denied, open '/home/user/.claude.json'). Run `claude mcp get example` to check, then add the server again if it is missing.3576MCP server "example" may not have been saved: /home/user/.claude.json could not be read to confirm the change (EACCES: permission denied, open '/home/user/.claude.json'). Run `claude mcp get example` to check, then add the server again if it is missing.
3490 3578
3491제거 후에는 메시지가 `may not have been removed`로 표시되고 `then remove the server again if it is still listed`로 끝납니다.3579제거 후에는 메시지가 `may not have been removed`로 표시되고 `then remove the server again if it is still listed`로 끝납니다.
3492 3580
3493v2.1.283 이전에는 변경 사항을 확인할 수 없는 경우에도 명령이 성공을 보고했습니다.3581v2.1.283 이전에는 변경 사항을 확인할 수 없어도 명령이 성공을 보고했습니다.
3494 3582
3495**해결 방법:**3583**해결 방법:**
3496 3584
3497* `claude mcp get <name>`을 실행하여 변경 사항이 디스크에 있는지 확인합니다. `local` 범위 서버의 경우 로컬 범위는 프로젝트별이므로 서버가 속한 프로젝트 디렉터리에서 실행합니다.3585* `claude mcp get <name>`을 실행해 변경 사항이 디스크에 반영되었는지 확인합니다. `local` 범위 서버의 경우 로컬 범위는 프로젝트별이므로 서버가 속한 프로젝트 디렉터리에서 실행합니다.
3498* 추가 후 서버가 없거나 제거 후에도 여전히 목록에 있으면 같은 추가 또는 제거 명령을 다시 실행합니다.3586* 추가 후 서버가 없거나 제거 후에도 여전히 목록에 있으면 같은 추가 또는 제거 명령을 다시 실행합니다.
3499 3587
3500### 서버가 Anthropic에서 호스팅되며 로컬 OAuth를 지원하지 않음3588### Server is Anthropic-hosted and doesn't support local OAuth
3501 3589
3502URL이 타사 ID 공급자를 통해 인증하는 Anthropic 호스팅 커넥터 호스트를 가리키는 MCP 서버에 대해 로그인을 시작했습니다. 이러한 호스트에는 `microsoft365.mcp.claude.com`, `gmail.mcp.claude.com`, `gcal.mcp.claude.com`이 포함됩니다. [이들의 로그인은 claude.ai를 통해서만 작동](https://code.claude.com/docs/ko/mcp.md#use-mcp-servers-from-claude-ai)하므로, Claude Code는 `/mcp` 패널과 `claude mcp login` 모두에서 이러한 호스트에 대한 로컬 OAuth 흐름 시작을 거부합니다.3590타사 ID 공급자를 통해 인증하는 Anthropic 호스팅 커넥터 호스트를 URL로 가리키는 MCP 서버에 대해 로그인을 시작했습니다. 이러한 호스트에는 `microsoft365.mcp.claude.com`, `gmail.mcp.claude.com`, `gcal.mcp.claude.com`이 포함됩니다. [이 호스트의 로그인은 claude.ai를 통해서만 작동하므로](https://code.claude.com/docs/ko/mcp.md#use-mcp-servers-from-claude-ai) Claude Code는 `/mcp` 패널과 `claude mcp login` 모두에서 이러한 호스트에 대한 로컬 OAuth 흐름 시작을 거부합니다.
3503 3591
3504```text theme={null}3592```text theme={null}
3505"gmail" is Anthropic-hosted and doesn't support local OAuth. Connect it via Settings → Connectors on claude.ai (requires `claude login`), then it'll be available here automatically.3593"gmail" is Anthropic-hosted and doesn't support local OAuth. Connect it via Settings → Connectors on claude.ai (requires `claude login`), then it'll be available here automatically.
3507 3595
3508**해결 방법:**3596**해결 방법:**
3509 3597
3510* 같은 URL의 claude.ai 커넥터를 가리지 않도록 `claude mcp remove <name>`으로 항목을 제거합니다3598* 같은 URL의 claude.ai 커넥터를 가리지 않도록 `claude mcp remove <name>`으로 해당 항목을 제거합니다
3511* 제거한 후 Claude Code에서 사용하는 계정으로 로그인한 상태에서 [claude.ai/customize/connectors](https://claude.ai/customize/connectors)에서 서비스를 연결합니다. 연결되면 활성 인증 방법이 claude.ai 구독 로그인인 경우 [커넥터가 Claude Code에 자동으로 표시됩니다](https://code.claude.com/docs/ko/mcp.md#use-mcp-servers-from-claude-ai)3599* 제거한 후 Claude Code에서 사용하는 계정으로 로그인한 상태에서 [claude.ai/customize/connectors](https://claude.ai/customize/connectors)에서 서비스를 연결합니다. 연결되면 활성 인증 방법이 claude.ai 구독 로그인인 경우 [커넥터가 Claude Code에 자동으로 나타납니다](https://code.claude.com/docs/ko/mcp.md#use-mcp-servers-from-claude-ai)
3512 3600
3513### 구성된 headersHelper가 생성한 Authorization 헤더를 서버가 거부함3601### Server rejected the Authorization header minted by the configured headersHelper
3514 3602
3515[`headersHelper`](https://code.claude.com/docs/ko/mcp#use-dynamic-headers-for-custom-authentication)가 `Authorization` 헤더를 제공하는 MCP 서버가 연결에 HTTP 401 또는 403으로 응답했기 때문에 Claude Code가 연결을 실패로 보고합니다. 헬퍼가 `Authorization` 헤더를 제공하므로 Claude Code는 해당 서버에 대해 [OAuth로 폴백하지 않습니다](https://code.claude.com/docs/ko/mcp.md#authenticate-with-remote-mcp-servers):3603[`headersHelper`](https://code.claude.com/docs/ko/mcp#use-dynamic-headers-for-custom-authentication)가 `Authorization` 헤더를 제공하는 MCP 서버가 연결에 HTTP 401 또는 403으로 응답했으므로 Claude Code는 연결 실패를 보고합니다. 헬퍼가 `Authorization` 헤더를 제공하므로 Claude Code는 해당 서버에 대해 [OAuth로 폴백하지 않습니다](https://code.claude.com/docs/ko/mcp.md#authenticate-with-remote-mcp-servers).
3516 3604
3517```text theme={null}3605```text theme={null}
3518Server rejected the Authorization header minted by the configured headersHelper (HTTP 401). Check that the helper command returns a valid credential for this MCP endpoint — OAuth fallback is disabled when the helper supplies Authorization.3606Server rejected the Authorization header minted by the configured headersHelper (HTTP 401). Check that the helper command returns a valid credential for this MCP endpoint — OAuth fallback is disabled when the helper supplies Authorization.
3519```3607```
3520 3608
3521Claude Code는 연결을 시도할 때마다 헬퍼를 다시 실행하므로, 토큰 교체 경합처럼 일시적인 거부 이후의 재시도는 새 자격 증명으로 성공할 수 있습니다.3609Claude Code는 연결을 시도할 때마다 헬퍼를 다시 실행하므로, 토큰 교체 경합 같은 일시적인 거부 후 재시도하면 새 자격 증명으로 성공할 수 있습니다.
3522 3610
3523**해결 방법:**3611**해결 방법:**
3524 3612
3525* Claude Code가 실행하는 방식 그대로 `headersHelper` 명령을 직접 실행합니다. [Claude Code가 실행하는 디렉터리](https://code.claude.com/docs/ko/mcp.md#where-the-helper-runs)에서, [Claude Code가 설정하는 환경 변수](https://code.claude.com/docs/ko/mcp.md#use-dynamic-headers-for-custom-authentication)와 함께, 그리고 프로젝트 `.mcp.json`, 플러그인 또는 프로젝트 에이전트 파일의 서버인 경우 [Claude Code가 제거하는 자격 증명 변수](https://code.claude.com/docs/ko/mcp.md#which-variables-a-helper-can-read) 없이 실행합니다. 서버의 엔드포인트가 수락하는 `Authorization` 값이 출력되는지 확인합니다3613* Claude Code가 실행하는 방식 그대로 `headersHelper` 명령을 직접 실행합니다. 즉, [Claude Code가 실행하는 디렉터리](https://code.claude.com/docs/ko/mcp.md#where-the-helper-runs)에서 [Claude Code가 설정하는 환경 변수](https://code.claude.com/docs/ko/mcp.md#use-dynamic-headers-for-custom-authentication)와 함께 실행하고, 프로젝트 `.mcp.json`, 플러그인 또는 프로젝트 에이전트 파일에서 온 서버라면 [Claude Code가 제거하는 자격 증명 변수](https://code.claude.com/docs/ko/mcp.md#which-variables-a-helper-can-read) 없이 실행합니다. 서버의 엔드포인트가 받아들이는 `Authorization` 값을 출력하는지 확인합니다
3526* 헬퍼나 자격 증명 소스를 수정한 후 `/mcp`에서 서버를 선택하고 **Reconnect**를 선택합니다3614* 헬퍼나 자격 증명 소스를 수정한 후 `/mcp`에서 서버를 선택하고 **Reconnect**를 선택합니다
3527 3615
3528v2.1.248 이전에는 헬퍼가 `Authorization` 헤더를 제공하는 서버에 대해서도 Claude Code가 OAuth 검색을 실행했습니다. 이 검색은 거부된 자격 증명을 보고하는 대신 `Incompatible auth server: does not support dynamic client registration`으로 실패할 수 있었습니다.3616v2.1.248 이전에는 헬퍼가 `Authorization` 헤더를 제공하는 서버에 대해서도 Claude Code가 OAuth 검색을 실행했습니다. 이 검색은 거부된 자격 증명을 보고하는 대신 `Incompatible auth server: does not support dynamic client registration`으로 실패할 수 있었습니다.
3529 3617
3530### MCP server rejected the elicitation capability3618### MCP server rejected the elicitation capability
3531 3619
3532Java MCP SDK 0.11.0부터 0.17.0까지로 빌드된 MCP 서버가 연결을 거부했습니다. 이 SDK 버전은 Claude Code가 핸드셰이크에서 선언하는 `form` 및 `url` [elicitation 모드](https://code.claude.com/docs/ko/mcp.md#elicitation-modes-claude-code-declares)를 파싱할 수 없습니다. 메시지는 다음과 같습니다:3620Java MCP SDK 0.11.0부터 0.17.0까지로 빌드된 MCP 서버가 연결을 거부했습니다. 해당 SDK 버전은 Claude Code가 핸드셰이크에서 선언하는 `form` 및 `url` [elicitation 모드](https://code.claude.com/docs/ko/mcp.md#elicitation-modes-claude-code-declares)를 구문 분석하지 못합니다. 메시지는 다음과 같습니다.
3533 3621
3534```text theme={null}3622```text theme={null}
3535This server (Java MCP SDK 0.17.0 or older) rejected Claude Code's elicitation capability. Set "bareElicitationCapability": true for it, or upgrade to Java MCP SDK 0.17.1+ (Spring AI 1.0.7+ or 1.1.6+).3623This server (Java MCP SDK 0.17.0 or older) rejected Claude Code's elicitation capability. Set "bareElicitationCapability": true for it, or upgrade to Java MCP SDK 0.17.1+ (Spring AI 1.0.7+ or 1.1.6+).
3538**해결 방법:**3626**해결 방법:**
3539 3627
3540* 서버를 Java MCP SDK 0.17.1 이상 또는 메시지에 표시된 Spring AI 릴리스 중 하나로 업그레이드합니다3628* 서버를 Java MCP SDK 0.17.1 이상 또는 메시지에 표시된 Spring AI 릴리스 중 하나로 업그레이드합니다
3541* 또는 MCP 구성의 해당 서버 항목에 `"bareElicitationCapability": true`를 추가한 뒤 Claude Code를 다시 시작합니다. 이 필드는 stdio, `sse`, `http`, `ws` 항목에서 허용되며 Claude Code v2.1.281 이상이 필요합니다3629* 또는 MCP 구성에서 해당 서버 항목에 `"bareElicitationCapability": true`를 추가한 다음 Claude Code를 다시 시작합니다. 이 필드는 stdio, `sse`, `http`, `ws` 항목에서 사용할 수 있으며 Claude Code v2.1.281 이상이 필요합니다
3542 3630
3543다음 `.mcp.json` 항목은 하나의 HTTP 서버에 이 필드를 설정합니다:3631다음 `.mcp.json` 항목은 하나의 HTTP 서버에 이 필드를 설정합니다.
3544 3632
3545```json theme={null}3633```json theme={null}
3546{3634{
3554}3642}
3555```3643```
3556 3644
3557다시 시작한 후 `/mcp`에서 서버가 연결된 것으로 표시됩니다. Claude Code는 해당 서버에만 form 모드를 선언하므로, 서버를 업그레이드하면 이 필드를 제거합니다.3645다시 시작한 후 `/mcp`에 서버가 연결됨으로 표시됩니다. Claude Code는 해당 서버에만 form 모드를 선언하므로, 서버를 업그레이드하면 이 필드를 제거합니다.
3558 3646
3559서버가 `Unrecognized field "form"`이 포함된 오류처럼 자체 오류 텍스트로 실패할 수도 있습니다. 같은 해결 방법이 적용됩니다.3647서버가 `Unrecognized field "form"`이 포함된 오류처럼 자체 오류 텍스트로 실패할 수도 있습니다. 같은 해결 방법이 적용됩니다.
3560 3648
3561### MCP 권한 프롬프트 도구를 찾을 수 없음3649### MCP permission prompt tool not found
3562 3650
3563실행에서 처음으로 권한 결정이 필요했을 때 [`--permission-prompt-tool`](https://code.claude.com/docs/ko/cli-reference#cli-flags)에 전달한 도구가 연결된 MCP 도구 중에 없었습니다. 해당 서버가 연결되지 않았거나, 연결된 서버 중 그 이름의 도구를 노출하는 서버가 없기 때문입니다. Claude Code는 여전히 프롬프트를 전송합니다. [비대화형](https://code.claude.com/docs/ko/headless.md) 실행은 첫 번째 도구 호출에서 이 오류와 종료 코드 1로 종료되므로, 요청은 이루어졌지만 응답은 생성되지 않습니다. 첫 번째 프롬프트 전에 Claude Code는 [`MCP_TIMEOUT`](https://code.claude.com/docs/ko/env-vars)으로 설정된 서버별 연결 타임아웃인 최대 30초 동안 해당 서버가 연결되기를 기다립니다. v2.1.206 이전에는 시작 시 서버 연결이 완료될 때까지 기다리지 않았기 때문에, 시작이 느리지만 정상인 서버에서도 이 오류가 발생했습니다.3651[`--permission-prompt-tool`](https://code.claude.com/docs/ko/cli-reference#cli-flags)에 전달한 도구가 실행에서 처음 권한 결정이 필요했을 때 연결된 MCP 도구 중에 없었습니다. 서버가 연결되지 않았거나, 연결된 서버 중 해당 이름의 도구를 노출하는 서버가 없기 때문입니다. Claude Code는 여전히 프롬프트를 전송합니다. [비대화형](https://code.claude.com/docs/ko/headless.md) 실행은 첫 번째 도구 호출에서 이 오류와 종료 코드 1로 종료되므로, 요청은 이루어졌지만 응답은 생성되지 않습니다. 첫 번째 프롬프트 전에 Claude Code는 [`MCP_TIMEOUT`](https://code.claude.com/docs/ko/env-vars)으로 설정된 서버별 연결 타임아웃인 최대 30초 동안 해당 서버가 연결되기를 기다립니다. v2.1.206 이전에는 시작 시 서버 연결 완료를 기다리지 않았으므로, 시작이 느리지만 정상적인 서버에서도 이 오류가 발생했습니다.
3564 3652
3565```text theme={null}3653```text theme={null}
3566Error: MCP tool mcp__permissions__approve (passed via --permission-prompt-tool) not found. Available MCP tools: none3654Error: MCP tool mcp__permissions__approve (passed via --permission-prompt-tool) not found. Available MCP tools: none
3570 3658
3571**해결 방법:**3659**해결 방법:**
3572 3660
3573* 서버가 시작되어 연결을 유지하는지 확인합니다. 같은 디렉터리에서 `claude mcp list`를 실행하고 서버가 연결된 상태로 표시되는지 확인합니다3661* 서버가 시작되고 연결이 유지되는지 확인합니다. 같은 디렉터리에서 `claude mcp list`를 실행하고 서버가 연결됨으로 표시되는지 확인합니다
3574* 도구 이름이 서버가 노출하는 `mcp__<server>__<tool>` 이름과 일치하는지 확인합니다3662* 도구 이름이 서버가 노출하는 `mcp__<server>__<tool>` 이름과 일치하는지 확인합니다
3575* 서버 시작에 30초 넘게 걸리면 [`MCP_TIMEOUT`](https://code.claude.com/docs/ko/env-vars)을 늘립니다3663* 서버 시작에 30초보다 오래 걸리면 [`MCP_TIMEOUT`](https://code.claude.com/docs/ko/env-vars)을 늘립니다
3576 3664
3577### OAuth 콜백 포트가 이미 사용 중임3665### OAuth callback port is already in use
3578 3666
3579OAuth로 원격 MCP 서버에 로그인하면 Claude Code는 로그인 콜백을 받기 위해 로컬 리스너를 시작합니다. 리스너에 필요한 포트를 다른 프로세스가 점유하고 있으면 이 메시지와 함께 로그인이 실패합니다. 이는 주로 [`MCP_OAUTH_CALLBACK_PORT`](https://code.claude.com/docs/ko/env-vars) 변수나 `--callback-port`로 [고정 콜백 포트](https://code.claude.com/docs/ko/mcp.md#use-a-fixed-oauth-callback-port)를 설정한 경우에 발생합니다. 고정 포트가 없으면 Claude Code가 사용 가능한 포트를 선택하기 때문입니다.3667OAuth로 원격 MCP 서버에 로그인하면 Claude Code는 로그인 콜백을 받기 위해 로컬 리스너를 시작합니다. 리스너에 필요한 포트를 다른 프로세스가 점유하고 있으면 로그인이 이 메시지와 함께 실패합니다. Claude Code는 고정 포트가 없으면 사용 가능한 포트를 선택하므로, 이 문제는 주로 [`MCP_OAUTH_CALLBACK_PORT`](https://code.claude.com/docs/ko/env-vars) 변수나 `--callback-port`로 설정한 [고정 콜백 포트](https://code.claude.com/docs/ko/mcp.md#use-a-fixed-oauth-callback-port)에서 발생합니다.
3580 3668
3581```text theme={null}3669```text theme={null}
3582OAuth callback port <port> is already in use — another process may be holding it. Run `lsof -ti:<port> -sTCP:LISTEN` to find it.3670OAuth callback port <port> is already in use — another process may be holding it. Run `lsof -ti:<port> -sTCP:LISTEN` to find it.
3586 3674
3587**해결 방법:**3675**해결 방법:**
3588 3676
3589* 메시지의 명령을 실행하여 포트를 점유한 프로세스를 찾고, 해당 프로세스를 중지하거나 완료될 때까지 기다립니다3677* 메시지의 명령을 실행해 포트를 점유한 프로세스를 찾고, 이를 중지하거나 완료될 때까지 기다립니다
3590* 다른 프로그램이 해당 포트를 계속 사용해야 한다면 서버에 다른 리디렉션 URI를 등록하고, 사용하는 방식에 따라 `MCP_OAUTH_CALLBACK_PORT` 또는 `--callback-port`로 그 포트를 설정합니다3678* 다른 프로그램이 해당 포트를 계속 사용해야 한다면 서버에 다른 리디렉션 URI를 등록하고, 사용 중인 방식에 따라 `MCP_OAUTH_CALLBACK_PORT` 또는 `--callback-port`로 해당 포트를 설정합니다
3591* 그런 다음 `/mcp`에서 서버를 선택하는 등의 방법으로 로그인을 다시 시작합니다3679* 그런 다음 `/mcp`에서 서버를 선택하는 등의 방법으로 로그인을 다시 시작합니다
3592 3680
3593### OAuth 리디렉션에 사용할 수 있는 포트가 없음3681### No available ports for OAuth redirect
3594 3682
3595[OAuth](https://code.claude.com/docs/ko/mcp.md#authenticate-with-remote-mcp-servers)로 원격 MCP 서버에 로그인하면 Claude Code는 로그인 콜백을 받기 위해 로컬 리스너를 시작합니다. Claude Code가 이를 위한 로컬 포트를 바인딩할 수 없으면 이 메시지와 함께 로그인이 실패합니다. 보안 소프트웨어나 로컬 리스너를 거부하는 샌드박스 정책처럼 시스템의 무언가가 `127.0.0.1`에서의 수신을 막고 있습니다.3683[OAuth](https://code.claude.com/docs/ko/mcp.md#authenticate-with-remote-mcp-servers)로 원격 MCP 서버에 로그인하면 Claude Code는 로그인 콜백을 받기 위해 로컬 리스너를 시작합니다. Claude Code가 이를 위한 로컬 포트를 바인딩할 수 없으면 로그인이 이 메시지와 함께 실패합니다. 보안 소프트웨어나 로컬 리스너를 거부하는 샌드박스 정책 등 컴퓨터의 무언가가 `127.0.0.1`에서의 수신을 막고 있습니다.
3596 3684
3597```text theme={null}3685```text theme={null}
3598No available ports for OAuth redirect3686No available ports for OAuth redirect
3599```3687```
3600 3688
3601v2.1.268 이전에는 Claude Code가 운영 체제가 할당한 포트로 폴백하지 않았기 때문에, 자체적으로 선택한 포트만 바인딩할 수 없는 경우에도 이 메시지가 표시되었습니다. 이는 Hyper-V가 Claude Code가 선택하는 포트를 포함하는 포트 범위를 예약하는 Windows 호스트에서 발생할 수 있습니다.3689v2.1.268 이전에는 Claude Code가 운영 체제가 할당한 포트로 폴백하지 않았으므로, 자체적으로 선택한 포트만 바인딩할 수 없는 경우에도 이 메시지가 나타났습니다. 이는 Hyper-V가 Claude Code가 선택하는 포트를 포함하는 포트 범위를 예약하는 Windows 호스트에서 발생할 수 있습니다.
3602 3690
3603**해결 방법:**3691**해결 방법:**
3604 3692
3605* 보안 소프트웨어나 샌드박스 정책이 프로세스의 `127.0.0.1` 수신을 차단하는지 확인하고, Claude Code가 로컬 포트를 바인딩하도록 허용합니다3693* 보안 소프트웨어나 샌드박스 정책이 프로세스의 `127.0.0.1` 수신을 차단하는지 확인하고, Claude Code가 로컬 포트를 바인딩할 수 있도록 허용합니다
3606* 그런 다음 `/mcp`에서 서버를 선택하는 등의 방법으로 로그인을 다시 시작합니다3694* 그런 다음 `/mcp`에서 서버를 선택하는 등의 방법으로 로그인을 다시 시작합니다
3607 3695
3608### origin/HEAD가 없으면 /security-review가 실패함3696### origin/HEAD가 없으면 /security-review가 실패함
3609 3697
3610[`/security-review`](https://code.claude.com/docs/ko/commands#all-commands)는 `origin` 원격의 기본 브랜치를 기록하는 로컬 ref인 `origin/HEAD`와 현재 브랜치를 비교한 diff로 리뷰 컨텍스트를 구성합니다. 해당 ref가 없으면 diff를 수집하는 git 명령이 실패하고 리뷰가 시작되기 전에 중단됩니다.3698[`/security-review`](https://code.claude.com/docs/ko/commands#all-commands)는 브랜치를 `origin/HEAD`와 비교한 diff로 리뷰 컨텍스트를 구성합니다. `origin/HEAD`는 `origin` 원격의 기본 브랜치가 무엇인지 기록하는 로컬 ref입니다. 이 ref가 없으면 diff를 수집하는 git 명령이 실패하고 리뷰가 시작되기 전에 중단됩니다.
3611 3699
3612```text theme={null}3700```text theme={null}
3613Error: Shell command failed for pattern "!`git diff --name-only origin/HEAD...`": [stderr]3701Error: Shell command failed for pattern "!`git diff --name-only origin/HEAD...`": [stderr]
3616'git <command> [<revision>...] -- [<file>...]'3704'git <command> [<revision>...] -- [<file>...]'
3617```3705```
3618 3706
3619메시지에 `git log`나 다른 `git diff`가 대신 표시될 수도 있습니다. Git은 원격이 기본 브랜치를 알리고 fetch refspec이 그 브랜치를 포함할 때만 `origin/HEAD`를 만듭니다. 커밋이 있는 원격을 전체 `git clone`하면 이 조건이 충족됩니다. 다음과 같은 환경에서는 ref가 없습니다:3707메시지에 `git log`나 다른 `git diff`가 대신 인용될 수도 있습니다. Git은 원격이 기본 브랜치를 알리고 fetch refspec이 이를 포함할 때만 `origin/HEAD`를 만들며, 커밋이 있는 원격을 전체 `git clone`하면 이 조건이 충족됩니다. 다음 구성에서는 ref가 없습니다.
3620 3708
3621* 너무 좁은 refspec을 가져오는 단일 브랜치 또는 CI 체크아웃3709* 너무 좁은 refspec을 fetch하는 단일 브랜치 또는 CI 체크아웃
3622* 서버 측 HEAD가 아무도 푸시하지 않은 브랜치를 가리키는 원격3710* 서버 측 HEAD가 아무도 푸시하지 않은 브랜치를 가리키는 원격
3623* `origin` 원격이 없거나 한 번도 fetch하지 않은 저장소3711* `origin` 원격이 없거나 한 번도 fetch하지 않은 저장소
3624 3712
3625Claude Code는 [동적 컨텍스트를 주입하는](https://code.claude.com/docs/ko/skills.md#when-an-injected-command-fails) 모든 스킬에 대해 같은 오류를 표시하며, 주입된 명령이 실패하면 해당 스킬 호출이 중단됩니다.3713Claude Code는 [동적 컨텍스트를 주입하는](https://code.claude.com/docs/ko/skills.md#when-an-injected-command-fails) 모든 스킬에 대해 같은 오류를 표시하며, 주입된 명령이 실패하면 해당 스킬의 호출이 중단됩니다.
3626 3714
3627관련 메시지는 명령이 실행되기도 전에 발생합니다:3715명령이 실행되기 전에 발생하는 관련 메시지도 있습니다.
3628 3716
3629* `Shell command permission check failed for pattern "..."`: 명령의 권한 검사가 허용하지 않았습니다. [주입된 명령의 권한 검사](https://code.claude.com/docs/ko/skills.md#permission-checks-on-injected-commands)에서 각 권한 모드에서 어떤 결과가 중단되는지와 `allowed-tools`로 명령을 미리 승인하는 방법을 다룹니다3717* `Shell command permission check failed for pattern "..."`: 명령의 권한 검사에서 허용되지 않았습니다. [주입된 명령의 권한 검사](https://code.claude.com/docs/ko/skills.md#permission-checks-on-injected-commands)에서 각 권한 모드에서 어떤 결과가 중단을 일으키는지, 그리고 `allowed-tools`로 명령을 사전 승인하는 방법을 설명합니다
3630* ``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)을 참조하세요3718* ``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)을 참조하세요
3631 3719
3632**해결 방법:**3720**해결 방법:**
3633 3721
3634* 원격의 기본 브랜치 이름을 지정하여 ref를 만듭니다: `git remote set-head origin <default-branch>`. 이는 로컬 추적 ref `origin/<default-branch>`가 있으면 항상 작동합니다. 단일 브랜치 클론처럼 해당 ref가 없으면 먼저 브랜치를 fetch합니다. `git remote set-branches --add origin <branch>`를 실행하고, 이어서 `git fetch origin`을 실행한 다음, set-head 명령을 다시 실행합니다. 그런 다음 `/security-review`를 다시 실행합니다.3722* 원격의 기본 브랜치를 지정해 ref를 만듭니다: `git remote set-head origin <default-branch>`. 이 방법은 로컬 추적 ref `origin/<default-branch>`가 있으면 항상 작동합니다. 단일 브랜치 클론처럼 해당 ref가 없으면 먼저 브랜치를 fetch합니다. `git remote set-branches --add origin <branch>`를 실행한 다음 `git fetch origin`을 실행하고, set-head 명령을 다시 실행합니다. 그런 다음 `/security-review`를 다시 실행합니다.
3635* 브랜치 이름을 지정하고 싶지 않다면 `git fetch origin`을 실행한 다음 `git remote set-head origin --auto`를 실행합니다. 이 명령은 원격에 기본 브랜치가 무엇인지 묻습니다. 원격이 비어 있거나 HEAD가 아무도 푸시하지 않은 브랜치를 가리켜 기본 브랜치를 알리지 않으면 `error: Cannot determine remote HEAD`로 실패하므로, 대신 브랜치 이름을 명시적으로 지정합니다. 클론이 해당 브랜치를 fetch하지 않으면 `error: Not a valid ref`로 실패하므로, 먼저 위와 같이 refspec을 넓힙니다.3723* 브랜치 이름을 지정하고 싶지 않다면 `git fetch origin`을 실행한 다음 `git remote set-head origin --auto`를 실행합니다. 이 명령은 원격에 기본 브랜치를 묻습니다. 원격이 비어 있거나 HEAD가 아무도 푸시하지 않은 브랜치를 가리켜 기본 브랜치를 알리지 않으면 `error: Cannot determine remote HEAD`로 실패하므로, 이 경우 브랜치를 명시적으로 지정합니다. 클론이 해당 브랜치를 fetch하지 않으면 `error: Not a valid ref`로 실패하므로, 먼저 위와 같이 refspec을 넓힙니다.
3636* 저장소에 원격이 없으면 `git remote add origin <url>`로 원격을 추가하고 ref를 만들기 전에 fetch합니다. 원격이 비어 있으면 먼저 `git push -u origin HEAD`로 브랜치를 푸시하고 set-head 명령에 해당 브랜치 이름을 지정합니다. 그러면 `origin/HEAD`가 방금 푸시한 브랜치를 가리키므로, 브랜치가 그로부터 갈라질 때까지 `/security-review`는 빈 diff를 보게 됩니다.3724* 저장소에 원격이 없으면 `git remote add origin <url>`로 원격을 추가하고 ref를 만들기 전에 fetch합니다. 원격이 비어 있으면 먼저 `git push -u origin HEAD`로 브랜치를 푸시하고 set-head 명령에 해당 브랜치를 지정합니다. 그러면 `origin/HEAD`가 방금 푸시한 브랜치를 가리키므로, 브랜치가 여기서 갈라질 때까지 `/security-review`에는 빈 diff가 표시됩니다.
3637 3725
3638### No shell command in a skill or command was run3726### No shell command in a skill or command was run
3639 3727
3640`No shell command in <name> was run`은 해당 스킬 또는 명령 파일의 `` !`<command>` `` [동적 컨텍스트 명령](https://code.claude.com/docs/ko/skills.md#inject-dynamic-context)에 Bash 또는 PowerShell 도구가 거부하는 문자가 포함되어 있다는 의미입니다:3728`No shell command in <name> was run`은 해당 스킬 또는 명령 파일의 `` !`<command>` `` [동적 컨텍스트 명령](https://code.claude.com/docs/ko/skills.md#inject-dynamic-context)에 Bash 또는 PowerShell 도구가 거부하는 문자가 포함되어 있다는 의미입니다.
3641 3729
3642* **두 도구 모두**: 탭이나 줄 바꿈이 아닌 원시 제어 문자3730* **두 도구 모두**: 탭이나 줄 바꿈이 아닌 원시 제어 문자
3643* **PowerShell 도구**: 추가로 U+FEFF 또는 U+180E3731* **PowerShell 도구**: 추가로 U+FEFF 또는 U+180E
3644 3732
3645메시지는 거부된 명령으로 끝나며, 거부된 각 문자는 다음 Bash 도구 예시처럼 `�`로 표시됩니다:3733메시지는 거부된 명령으로 끝나며, 거부된 각 문자는 다음 Bash 도구 예시처럼 `�`로 표시됩니다.
3646 3734
3647```text theme={null}3735```text theme={null}
3648No shell command in /my-skill was run, because the Bash tool does not accept one of them: command contains control characters that would be hidden in the approval dialog. Unprintable characters are shown as � below: remove them from the skill or command file, or from the arguments or options substituted into it.3736No shell command in /my-skill was run, because the Bash tool does not accept one of them: command contains control characters that would be hidden in the approval dialog. Unprintable characters are shown as � below: remove them from the skill or command file, or from the arguments or options substituted into it.
3651 3739
3652**해결 방법:**3740**해결 방법:**
3653 3741
3654* 메시지 끝에 인용된 명령에서 각 `�`를 찾습니다. 그것이 나타내는 문자를 [스킬 또는 명령 파일](https://code.claude.com/docs/ko/skills.md#where-skills-live)에서, 또는 파일에 대입되는 인수나 [옵션](https://code.claude.com/docs/ko/plugins/manifest-reference.md#user-configuration)에서 제거합니다.3742* 메시지 끝에 인용된 명령에서 각 `�`를 찾습니다. 해당 문자를 [스킬 또는 명령 파일](https://code.claude.com/docs/ko/skills.md#where-skills-live)에서, 또는 파일에 대입된 인수나 [옵션](https://code.claude.com/docs/ko/plugins/manifest-reference.md#user-configuration)에서 제거합니다.
3655 3743
3656### `--print` 사용 시 입력을 제공해야 함3744### Input must be provided when using `--print`
3657 3745
3658인수 없는 `claude`는 대화형 UI를 시작하기 위해 stdout이 터미널이어야 합니다. stdout이 리디렉션되었거나, PowerShell ISE나 일부 IDE 출력 창처럼 콘솔이 실제 터미널이 아니면 `claude`는 대신 [비대화형으로](https://code.claude.com/docs/ko/headless.md) 실행됩니다. 이는 프롬프트가 필요한 `claude -p`와 같은 모드이므로, 플래그를 전달하지 않았더라도 메시지에 `--print`가 표시됩니다. 프롬프트 없이, stdin으로 파이프된 내용도 없이 `-p`/`--print`를 전달하면 어디서든 같은 오류가 발생합니다.3746인수 없는 `claude`는 대화형 UI를 시작하려면 stdout이 터미널이어야 합니다. stdout이 리디렉션되었거나 PowerShell ISE나 일부 IDE 출력 창처럼 콘솔이 실제 터미널이 아니면, `claude`는 대신 [비대화형으로](https://code.claude.com/docs/ko/headless.md) 실행됩니다. 이는 프롬프트가 필요한 `claude -p`와 같은 모드이므로, 플래그를 전달하지 않았어도 메시지에 `--print`가 표시됩니다. 프롬프트 없이 stdin으로 아무것도 파이프하지 않은 채 `-p`/`--print`를 전달해도 어디서든 같은 오류가 발생합니다.
3659 3747
3660```text theme={null}3748```text theme={null}
3661Error: Input must be provided either through stdin or as a prompt argument when using --print3749Error: Input must be provided either through stdin or as a prompt argument when using --print
3666* 대화형으로 사용하려면 실제 터미널에서 `claude`를 실행합니다. ISE 대신 Windows Terminal이나 PowerShell 콘솔을, 출력 창 대신 IDE의 통합 터미널을 사용합니다3754* 대화형으로 사용하려면 실제 터미널에서 `claude`를 실행합니다. ISE 대신 Windows Terminal이나 PowerShell 콘솔을, 출력 창 대신 IDE의 통합 터미널을 사용합니다
3667* 일회성으로 사용하려면 프롬프트를 전달합니다: `claude -p "your question"`, 또는 `echo "your question" | claude -p`로 파이프합니다3755* 일회성으로 사용하려면 프롬프트를 전달합니다: `claude -p "your question"`, 또는 `echo "your question" | claude -p`로 파이프합니다
3668 3756
3669### 이 환경에서는 Claude Code가 키보드 입력을 읽을 수 없음3757### Claude Code can't read the keyboard here
3670 3758
3671[`-p`](https://code.claude.com/docs/ko/headless) 없이 `claude`를 실행하여 [대화형 세션](https://code.claude.com/docs/ko/interactive-mode.md)을 시작했지만, 표준 입력이 터미널이 아닙니다. 무언가가 입력을 파이프하거나 리디렉션했거나, `claude`를 실행한 프로그램이 자체 입력 스트림을 제공했습니다.3759[`-p`](https://code.claude.com/docs/ko/headless) 없이 `claude`를 실행해 [대화형 세션](https://code.claude.com/docs/ko/interactive-mode.md)을 시작했지만, 표준 입력이 터미널이 아닙니다. 무언가가 입력을 파이프하거나 리디렉션했거나, `claude`를 실행한 프로그램이 자체 입력 스트림을 제공했습니다.
3672 3760
3673대화형 세션은 키 입력을 읽을 터미널이 필요하며, 터미널이 없을 때 Claude Code의 동작은 플랫폼에 따라 다릅니다:3761대화형 세션은 키 입력을 읽을 터미널이 필요하며, 터미널이 없을 때 Claude Code의 동작은 플랫폼에 따라 다릅니다.
3674 3762
3675* **Windows**: Claude Code는 인터페이스를 시작하지 않고 stderr에 메시지를 출력한 후 종료 코드 1로 종료됩니다3763* **Windows**: Claude Code는 인터페이스를 시작하지 않고 메시지를 stderr에 출력한 뒤 종료 코드 1로 종료됩니다
3676* **macOS 및 Linux**: Claude Code는 `/dev/tty`에서 키 입력을 읽어 세션을 시작하며, 파이프된 텍스트가 있으면 첫 번째 프롬프트로 사용합니다. `/dev/tty`를 열 수 없을 때 메시지가 표시되며, 첫 번째 줄에는 Windows 문구 대신 `/dev/tty`가 표시됩니다.3764* **macOS 및 Linux**: Claude Code는 `/dev/tty`에서 키 입력을 읽고 세션을 시작하며, 파이프된 텍스트가 있으면 첫 번째 프롬프트로 사용합니다. `/dev/tty`를 열 수 없을 때 메시지가 표시되며, 첫 번째 줄에는 Windows 문구 대신 `/dev/tty`가 표시됩니다.
3677 3765
3678Windows에서는 메시지가 다음과 같습니다:3766Windows에서 메시지는 다음과 같습니다.
3679 3767
3680```text theme={null}3768```text theme={null}
3681Claude Code can't read the keyboard here: stdin is not a terminal (it is piped, redirected, or supplied by the program that launched claude), and on Windows it can't fall back to the console for input yet.3769Claude Code can't read the keyboard here: stdin is not a terminal (it is piped, redirected, or supplied by the program that launched claude), and on Windows it can't fall back to the console for input yet.
3686**해결 방법:**3774**해결 방법:**
3687 3775
3688* 대화형으로 작업하려면 입력을 파이프하거나 리디렉션하지 않고 터미널에서 직접 `claude`를 실행합니다3776* 대화형으로 작업하려면 입력을 파이프하거나 리디렉션하지 않고 터미널에서 직접 `claude`를 실행합니다
3689* 스크립트에서처럼 대화형 인터페이스 없이 응답을 받으려면 `-p`를 추가하고 프롬프트를 인수나 stdin으로 전달합니다. 예: `claude -p "your question"` 또는 `echo "your question" | claude -p`. `--continue` 및 `--resume <session-id>`와도 같은 방식으로 작동합니다.3777* 스크립트 등에서 대화형 인터페이스 없이 응답을 받으려면 `-p`를 추가하고 `claude -p "your question"` 또는 `echo "your question" | claude -p`처럼 프롬프트를 인수나 stdin으로 전달합니다. `--continue` 및 `--resume <session-id>`에서도 같은 방식이 작동합니다.
3690 3778
3691v2.1.287 이전에는 Claude Code가 이 메시지를 출력하는 대신 인터페이스를 시작했고, 화면에 아무것도 표시하지 않거나 `Raw mode is not supported`가 포함된 오류로 실패했습니다.3779v2.1.287 이전에는 Claude Code가 이 메시지를 출력하는 대신 인터페이스를 시작했으며, 화면에 아무것도 표시하지 않거나 `Raw mode is not supported`가 포함된 오류로 실패했습니다.
3692 3780
3693대신 `claude install` 중에 `Raw mode is not supported`가 표시되면 [설치 중 `Raw mode is not supported`](https://code.claude.com/docs/ko/troubleshoot-install#raw-mode-is-not-supported-during-install)를 참조하십시오.3781`claude install` 중에 `Raw mode is not supported`가 표시되는 경우에는 [설치 중 `Raw mode is not supported`](https://code.claude.com/docs/ko/troubleshoot-install#raw-mode-is-not-supported-during-install)를 참조하세요.
3694 3782
3695### 입력에 공백만 포함됨3783### Input contained only whitespace
3696 3784
3697[비대화형 모드](https://code.claude.com/docs/ko/headless.md)에서 Claude Code는 공백, 탭 또는 줄 바꿈으로만 이루어진 프롬프트를 전송하지 않고 거부합니다. API가 보이는 텍스트가 없는 메시지를 거부하기 때문입니다. 표시되는 메시지는 빈 프롬프트가 어디에서 왔는지에 따라 다릅니다:3785[비대화형 모드](https://code.claude.com/docs/ko/headless.md)에서 Claude Code는 공백, 탭, 줄 바꿈으로만 이루어진 프롬프트를 전송하지 않고 거부합니다. API가 보이는 텍스트가 없는 메시지를 거부하기 때문입니다. 표시되는 메시지는 빈 프롬프트가 어디서 왔는지에 따라 다릅니다.
3698 3786
3699* **`claude -p`의 프롬프트 인수 또는 파이프된 stdin**: `claude`가 `Error: Input contained only whitespace. Provide a prompt with text through stdin or as a prompt argument when using --print`와 함께 종료됩니다3787* **`claude -p`의 프롬프트 인수 또는 파이프된 stdin**: `claude`가 `Error: Input contained only whitespace. Provide a prompt with text through stdin or as a prompt argument when using --print`와 함께 종료됩니다
3700* **실행 중인 `--input-format stream-json` 또는 [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/overview.md) 세션에 제출된 메시지**: Claude Code는 모델을 호출하지 않고 턴을 종료하며 세션은 계속 사용할 수 있습니다. 거부 내용은 정보 메시지와 턴의 결과 텍스트로 전달됩니다: `Blank prompt — the message was only whitespace, so nothing was sent to the model.`3788* **실행 중인 `--input-format stream-json` 또는 [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/overview.md) 세션에 제출된 메시지**: Claude Code는 모델을 호출하지 않고 턴을 종료하며 세션은 계속 사용할 수 있습니다. 거부 내용은 정보 메시지와 턴의 결과 텍스트로 전달됩니다: `Blank prompt — the message was only whitespace, so nothing was sent to the model.`
3701 3789
3702v2.1.229 이전에는 Claude Code가 공백만 있는 메시지를 API에 전송했고, API는 400 오류로 요청을 거부했습니다.3790v2.1.229 이전에는 Claude Code가 공백만 있는 메시지를 API로 전송했고, API가 400 오류로 요청을 거부했습니다.
3703 3791
3704**해결 방법:**3792**해결 방법:**
3705 3793
3706* 프롬프트에 보이는 텍스트를 포함합니다. 스크립트가 변수나 파일에서 프롬프트를 만든다면 Claude Code를 호출하기 전에 소스가 비어 있지 않은지 확인합니다.3794* 프롬프트에 보이는 텍스트를 포함합니다. 스크립트가 변수나 파일에서 프롬프트를 구성하는 경우 Claude Code를 호출하기 전에 소스가 비어 있지 않은지 확인합니다.
3707 3795
3708### stream-json 입력이 줄 바꿈 없이 256M 문자를 초과함3796### stream-json input carried over 256M characters with no newline
3709 3797
3710프로그램이 `claude -p --input-format stream-json` 실행의 stdin에 줄 바꿈 없이 268,435,456자를 넘게 보냈기 때문에, Claude Code는 더 이상 입력을 버퍼링하지 않고 stderr에 이 오류를 출력한 후 종료 코드 1로 종료됩니다. 메시지는 이 한도를 `256M`으로 표시합니다. v2.1.257 이전에는 Claude Code가 이러한 입력을 제한 없이 버퍼링하여, 프로세스가 충돌하거나 종료될 때까지 메모리가 증가했습니다.3798프로그램이 `claude -p --input-format stream-json` 실행에 줄 바꿈 없이 268,435,456자를 초과하는 입력을 stdin으로 보냈으므로, Claude Code는 입력을 더 버퍼링하지 않고 이 오류를 stderr에 출력한 뒤 종료 코드 1로 종료됩니다. 메시지에서는 이 한도를 `256M`으로 표시합니다. v2.1.257 이전에는 Claude Code가 이러한 입력을 제한 없이 버퍼링해 프로세스가 충돌하거나 강제 종료될 때까지 메모리가 증가했습니다.
3711 3799
3712```text theme={null}3800```text theme={null}
3713Error: stream-json input carried over 256M characters with no newline. Each stream-json message must be a single newline-terminated JSON line: either the producer is not newline-terminating its messages, or one message exceeded this budget.3801Error: stream-json input carried over 256M characters with no newline. Each stream-json message must be a single newline-terminated JSON line: either the producer is not newline-terminating its messages, or one message exceeded this budget.
3714```3802```
3715 3803
3716줄 바꿈 없이 이렇게 긴 입력은 대개 생산자가 애초에 stream-json 생산자가 아님을 의미합니다. 예를 들어 바이너리 파일이나 일반 로그 출력이 실수로 파이프된 경우입니다. 한도를 초과하는 단일 메시지도 같은 검사에서 실패합니다.3804줄 바꿈 없이 이렇게 긴 입력은 대개 실수로 파이프된 바이너리 파일이나 일반 로그 출력처럼 생산자가 애초에 stream-json 생산자가 아니라는 의미입니다. 한도를 초과하는 단일 메시지도 같은 검사에서 실패합니다.
3717 3805
3718**해결 방법:**3806**해결 방법:**
3719 3807
3720* stdin으로 무엇이 파이프되는지 확인합니다. [`--input-format stream-json`](https://code.claude.com/docs/ko/cli-reference#cli-flags)에서는 모든 메시지가 줄 바꿈으로 끝나는 JSON 한 줄이어야 합니다3808* stdin으로 무엇이 파이프되는지 확인합니다. [`--input-format stream-json`](https://code.claude.com/docs/ko/cli-reference#cli-flags)을 사용하면 모든 메시지는 줄 바꿈으로 끝나는 JSON 한 줄이어야 합니다
3721* 대신 일반 텍스트를 보내려면 `--input-format stream-json`을 제거합니다. `claude -p`는 기본적으로 stdin에서 일반 텍스트 프롬프트를 읽습니다3809* 대신 일반 텍스트를 보내려면 `--input-format stream-json`을 제거합니다. `claude -p`는 기본적으로 stdin에서 일반 텍스트 프롬프트를 읽습니다
3722 3810
3723### Unknown command3811### Unknown command
3724 3812
3725대화형 터미널 세션에서 이 세션의 어떤 명령과도 일치하지 않는 `/` 이름을 제출했기 때문에, Claude Code는 아무것도 실행하지 않고 해당 이름을 보고합니다:3813대화형 터미널 세션에서 이 세션의 어떤 명령과도 일치하지 않는 `/` 이름을 제출했기 때문에, Claude Code가 아무것도 실행하지 않고 해당 이름을 보고합니다:
3726 3814
3727```text theme={null}3815```text theme={null}
3728Unknown command: /hepl. Did you mean /help?3816Unknown command: /hepl. Did you mean /help?
3729```3817```
3730 3818
3731Claude Code는 이 세션의 메뉴에 나열된 명령 이름이나 별칭 중 가장 가까운 것을 제안합니다. 가까운 것이 없으면 메시지는 이름 뒤에서 끝납니다. 원인은 대개 다음 중 하나입니다:3819Claude Code는 이 세션에서 메뉴에 나열된 명령 이름 또는 별칭 중 가장 가까운 것을 제안합니다. 가까운 것이 없으면 메시지는 이름 뒤에서 끝납니다. 원인은 보통 다음 중 하나입니다:
3732 3820
3733* `/help`를 `/hepl`로 입력한 것 같은 오타. [명령 메뉴가 입력 내용과 일치시키는 방식](https://code.claude.com/docs/ko/commands.md#how-the-command-menu-matches-what-you-type)에서 제출 전에 가까운 항목을 선택하는 방법을 다룹니다3821* `/help` 대신 `/hepl`을 입력한 것과 같은 오타. 제출하기 전에 가까운 일치 항목을 고르는 방법은 [명령 메뉴가 입력 내용과 일치시키는 방식](https://code.claude.com/docs/ko/commands.md#how-the-command-menu-matches-what-you-type)에서 다룹니다
3734* 명령은 존재하지만 플랫폼, 플랜, 인증 방법 등의 요구 사항이 충족되지 않아 이 세션에서 사용할 수 없습니다. [`/web-setup`](https://code.claude.com/docs/ko/web-quickstart#web-setup-shows-no-commands-match-or-unknown-command), [`/schedule`](https://code.claude.com/docs/ko/routines#schedule-returns-unknown-command), [`/auto-mode-setup`](https://code.claude.com/docs/ko/auto-mode-config#auto-mode-setup-returns-unknown-command) 항목을 참조하세요. 일부 명령은 조직 정책에 의해 비활성화되었을 때 [`Cloud sessions are disabled by your organization's policy`](#cloud-sessions-are-disabled-by-your-organizations-policy)처럼 자체 메시지로 응답합니다3822* 존재하지만 플랫폼, 플랜, 인증 방법 등의 요구 사항이 충족되지 않아 이 세션에서 사용할 수 없는 명령. [`/web-setup`](https://code.claude.com/docs/ko/web-quickstart#web-setup-shows-no-commands-match-or-unknown-command), [`/schedule`](https://code.claude.com/docs/ko/routines#schedule-returns-unknown-command), [`/auto-mode-setup`](https://code.claude.com/docs/ko/auto-mode-config#auto-mode-setup-returns-unknown-command) 항목을 참조하십시오. 일부 명령은 조직의 정책으로 비활성화된 경우 [`Cloud sessions are disabled by your organization's policy`](#cloud-sessions-are-disabled-by-your-organizations-policy)와 같은 자체 메시지로 응답합니다
3735* 이 세션에 설치되거나 연결되지 않은 [플러그인](https://code.claude.com/docs/ko/plugins/overview.md) 또는 [MCP 서버](https://code.claude.com/docs/ko/mcp.md#use-mcp-prompts-as-commands)의 명령3823* 이 세션에 설치되지 않았거나 연결되지 않은 [플러그인](https://code.claude.com/docs/ko/plugins/overview.md) 또는 [MCP 서버](https://code.claude.com/docs/ko/mcp.md#use-mcp-prompts-as-commands)의 명령
3736 3824
3737Claude Code는 대화형 터미널 세션에서만 일치하지 않는 `/` 이름에 이런 방식으로 응답합니다. 그 밖의 모든 세션에서는 프롬프트를 일반 메시지로 Claude에 보내며, 명령이 실행되지 않았다는 메모와 세션에서 Claude가 실행할 수 있는 명령 목록을 함께 보냅니다. 이러한 세션은 다음과 같습니다:3825Claude Code는 대화형 터미널 세션에서만 일치하지 않는 `/` 이름에 이런 방식으로 응답합니다. 그 외의 모든 세션에서는 프롬프트를 일반 메시지로 Claude에 보내며, 명령이 실행되지 않았다는 안내와 세션에서 Claude가 실행할 수 있는 명령 목록을 함께 보냅니다. 해당 세션은 다음과 같습니다:
3738 3826
3739* `-p` 실행3827* `-p` 실행
3740* [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/overview.md) 애플리케이션3828* [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/overview.md) 애플리케이션
3741* [데스크톱 앱](https://code.claude.com/docs/ko/desktop.md)의 Code 탭3829* [Desktop 앱](https://code.claude.com/docs/ko/desktop.md)의 Code 탭
3742* [VS Code 확장](https://code.claude.com/docs/ko/vs-code.md)의 채팅 패널3830* [VS Code 확장 프로그램](https://code.claude.com/docs/ko/vs-code.md)의 채팅 패널
3743* [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md) 및 [클라우드 예약 작업](https://code.claude.com/docs/ko/routines.md)3831* [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md) 및 [클라우드 예약 작업](https://code.claude.com/docs/ko/routines.md)
3744 3832
3745이러한 세션 중 하나에서 실행할 수 없는 내장 명령의 경우, Claude Code는 Claude에 전송하지 않고 여전히 해당 명령을 사용할 수 없다고 응답합니다. v2.1.274 이전에는 클라우드 세션과 클라우드 예약 작업만 일치하지 않는 이름을 Claude에 전송했습니다. v2.1.273 이전에는 이들도 `Unknown command`로 응답했습니다.3833이러한 세션 중 하나에서 실행할 수 없는 기본 제공 명령의 경우, Claude Code는 여전히 Claude에 보내지 않고 해당 명령을 사용할 수 없다고 응답합니다. v2.1.274 이전에는 클라우드 세션과 클라우드 예약 작업만 일치하지 않는 이름을 Claude에 보냈습니다. v2.1.273 이전에는 이들도 `Unknown command`로 응답했습니다.
3746 3834
3747Claude Code는 `/`로 시작하는 모든 프롬프트를 명령으로 처리하지 않습니다. `/` 다음의 첫 단어가 Lean 문서 주석을 여는 `/--`처럼 문장 부호로 시작하거나 `/var/log/syslog` 같은 경로이면 프롬프트를 일반 메시지로 Claude에 보냅니다.3835Claude Code는 `/`로 시작하는 모든 프롬프트를 명령으로 처리하지 않습니다. `/` 뒤의 첫 단어가 Lean 문서 주석을 여는 `/--`처럼 구두점으로 시작하거나 `/var/log/syslog`와 같은 경로인 경우, 프롬프트를 일반 메시지로 Claude에 보냅니다.
3748 3836
3749v2.1.236 이전에는 명령 메뉴에 입력한 이름과 가까운 항목이 나열된 상태에서 `Enter`를 누르면 Claude Code가 그 항목을 실행했기 때문에, `/hepl` 같은 오타는 이 메시지를 표시하는 대신 `/help`를 실행했습니다.3837v2.1.236 이전에는 명령 메뉴에 입력한 이름과 가까운 항목이 나열된 상태에서 `Enter`를 누르면 Claude Code가 해당 항목을 실행했기 때문에, `/hepl`과 같은 오타는 이 메시지를 표시하는 대신 `/help`를 실행했습니다.
3750 3838
3751**해결 방법:**3839**해결 방법:**
3752 3840
3753* 제안된 이름을 실행하거나, `/` 다음에 이름의 일부를 입력하여 이 세션에서 사용 가능한 명령을 확인합니다3841* 제안된 이름을 실행하거나, `/` 뒤에 이름의 일부를 입력하여 이 세션에서 사용할 수 있는 명령을 확인합니다
3754* Claude Code가 문서화된 명령을 알 수 없는 명령으로 보고하면 [명령 참조](https://code.claude.com/docs/ko/commands.md)에서 해당 행에 명시된 요구 사항을 확인합니다3842* Claude Code가 문서화된 명령을 알 수 없다고 보고하는 경우, [명령 참조](https://code.claude.com/docs/ko/commands.md)에서 해당 명령의 행을 확인하여 명시된 요구 사항을 확인합니다
3755 3843
3756### diff가 너무 커서 ultrareview를 할 수 없음3844### Diff is too large for ultrareview
3757 3845
3758커밋되지 않은 변경 사항과 스테이징된 변경 사항을 포함하여 브랜치와 기본 브랜치 사이의 diff가 [ultrareview](https://code.claude.com/docs/ko/ultrareview.md)의 크기 제한을 초과했기 때문에, `/code-review ultra`와 `claude ultrareview` 하위 명령이 클라우드 세션 시작 전에 리뷰를 거부합니다. 거부된 리뷰는 무료 실행 횟수를 사용하지 않으며 사용량 크레딧도 청구되지 않습니다. 메시지에는 적용 중인 제한, diff 크기, 그리고 변경된 줄이 가장 많은 파일이 표시됩니다. v2.1.216 이전에는 메시지에 원시 diff 통계만 표시되었습니다.3846커밋되지 않은 변경 사항과 스테이징된 변경 사항을 포함하여 현재 브랜치와 기본 브랜치 간의 diff가 [ultrareview](https://code.claude.com/docs/ko/ultrareview.md)의 크기 제한을 초과하므로, `/code-review ultra`와 `claude ultrareview` 하위 명령은 클라우드 세션이 시작되기 전에 리뷰를 거부합니다. 거부된 리뷰는 무료 실행 횟수를 사용하지 않으며 사용량 크레딧도 청구되지 않습니다. 메시지에는 적용 중인 제한, diff의 크기, 변경된 줄 수가 가장 많은 파일이 표시됩니다. v2.1.216 이전에는 메시지에 원시 diff 통계만 표시되었습니다.
3759 3847
3760```text theme={null}3848```text theme={null}
3761Diff is too large for ultrareview: 812 files, 96,410 lines changed (limits: 500 files, 8,000 lines). Largest files: package-lock.json (41,904 lines), dist/bundle.js (18,210 lines), src/generated/api.ts (9,876 lines). Pass a closer base branch (`/code-review ultra <branch>`) to narrow the scope, or split the change.3849Diff is too large for ultrareview: 812 files, 96,410 lines changed (limits: 500 files, 8,000 lines). Largest files: package-lock.json (41,904 lines), dist/bundle.js (18,210 lines), src/generated/api.ts (9,876 lines). Pass a closer base branch (`/code-review ultra <branch>`) to narrow the scope, or split the change.
3762```3850```
3763 3851
3764풀 리퀘스트를 리뷰할 때도 같은 제한이 적용됩니다. 이 경우 메시지는 `PR #<N> is too large for ultrareview`로 시작하며 PR의 파일 수와 줄 수가 표시됩니다.3852풀 리퀘스트를 리뷰할 때도 동일한 제한이 적용됩니다. 이 경우 메시지는 `PR #<N> is too large for ultrareview`로 시작하며 PR의 파일 수와 줄 수를 표시합니다.
3765 3853
3766**해결 방법:**3854**해결 방법:**
3767 3855
3768* `/code-review ultra develop`처럼 작업에 더 가까운 기본 브랜치를 전달하여 리뷰가 해당 브랜치와의 diff만 다루도록 합니다3856* `/code-review ultra develop`처럼 작업에 더 가까운 기본 브랜치를 전달하여, 리뷰가 해당 브랜치와의 diff만 다루도록 합니다
3769* 변경 사항을 더 작은 브랜치로 나누고 각각 리뷰합니다. 메시지에 표시된 파일이 변경된 줄이 가장 많으므로, 먼저 해당 파일을 별도 브랜치로 옮기는 것부터 시작합니다.3857* 변경 사항을 더 작은 브랜치로 나누고 각각 리뷰합니다. 메시지에 표시된 파일이 변경된 줄 수가 가장 많으므로, 먼저 해당 파일을 별도의 브랜치로 옮기십시오.
3770 3858
3771### 기본 브랜치와의 merge-base를 찾을 수 없음3859### Could not find merge-base with the base branch
3772 3860
3773`/code-review ultra`와 `claude ultrareview` 하위 명령은 브랜치와 기본 브랜치 사이의 diff를 리뷰하며, 이를 위해서는 두 브랜치가 공유하는 커밋이 필요합니다. `git merge-base`가 그런 커밋을 찾지 못하면 Claude Code는 클라우드 세션 시작 전에 리뷰를 거부합니다. Claude Code가 완전한 것으로 확인할 수 있고 브랜치가 하나 이상 있는 클론에서는 거부하는 대신 [추적 중인 모든 파일을 리뷰](https://code.claude.com/docs/ko/ultrareview.md#diff-limits-and-fallbacks)하는 방식으로 폴백합니다. 이 거부는 기본 브랜치를 전혀 찾을 수 없을 때, Claude Code가 클론이 완전한지 확인할 수 없을 때, 또는 SHA-256 객체 형식처럼 전체 트리 diff가 불가능한 드문 저장소에서 표시됩니다.3861`/code-review ultra`와 `claude ultrareview` 하위 명령은 현재 브랜치와 기본 브랜치 간의 diff를 리뷰하며, 이를 위해서는 두 브랜치가 공유하는 커밋이 필요합니다. `git merge-base`가 공유 커밋을 찾지 못하면 Claude Code는 클라우드 세션이 시작되기 전에 리뷰를 거부합니다. Claude Code가 완전하다고 확인할 수 있고 브랜치가 하나 이상 있는 클론에서는 거부하는 대신 [추적되는 모든 파일을 리뷰하는 방식](https://code.claude.com/docs/ko/ultrareview.md#diff-limits-and-fallbacks)으로 대체합니다. 기본 브랜치를 전혀 찾을 수 없는 경우, Claude Code가 클론이 완전한지 확인할 수 없는 경우, 또는 SHA-256 객체 형식처럼 전체 트리 diff가 불가능한 드문 저장소에서 이 거부 메시지가 표시됩니다.
3774 3862
3775```text theme={null}3863```text theme={null}
3776Could not find merge-base with main. Pass the base branch explicitly (e.g. `/code-review ultra develop`) or make sure you're in a git repo with a main branch.3864Could not find merge-base with main. Pass the base branch explicitly (e.g. `/code-review ultra develop`) or make sure you're in a git repo with a main branch.
3777```3865```
3778 3866
3779첫 문장 뒤의 힌트는 Claude Code가 관찰한 내용에 따라 달라집니다:3867첫 번째 문장 뒤의 힌트는 Claude Code가 확인한 내용에 따라 달라집니다:
3780 3868
3781* **기본 브랜치를 전달하지 않은 경우**: Claude Code는 저장소의 기본 브랜치와 비교했으며, 위 예시처럼 기본 브랜치를 명시적으로 전달하도록 제안합니다3869* **기본 브랜치를 전달하지 않은 경우**: Claude Code는 저장소의 기본 브랜치와 비교했으며, 위 예시처럼 기본 브랜치를 명시적으로 전달하도록 제안합니다
3782* **클론에 이미 있는 기본 브랜치를 전달한 경우**: 힌트는 ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``입니다3870* **이미 클론에 있는 기본 브랜치를 전달한 경우**: 힌트는 ``Make sure <branch> exists locally or on origin (try `git fetch origin <branch>`)``입니다
3783* **클론에 없던 기본 브랜치를 전달한 경우**: 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`와 함께 실패했습니다.3871* **클론에 없는 기본 브랜치를 전달한 경우**: 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`와 함께 실패했습니다.
3784 3872
3785**해결 방법:**3873**해결 방법:**
3786 3874
3787* 다른 브랜치가 실제 기본 브랜치라면 명시적으로 전달합니다: `/code-review ultra <branch>`3875* 다른 브랜치가 실제 기본 브랜치라면 명시적으로 전달합니다: `/code-review ultra <branch>`
3788* 클론에 전체 히스토리가 없을 수 있다면 `git fetch --unshallow origin`을 실행하고 리뷰를 다시 실행합니다3876* 클론에 전체 기록이 없을 수 있다면 `git fetch --unshallow origin`을 실행하고 리뷰를 다시 실행합니다
3789 3877
3790### 체크아웃에 브랜치가 없음3878### Your checkout has no branches
3791 3879
3792체크아웃에는 커밋이 있어도 브랜치가 없을 수 있습니다. `git init`을 실행한 후 `git fetch <url>`과 `git checkout FETCH_HEAD`를 실행하면 ref가 없는 detached HEAD 상태가 됩니다. Claude Code는 [ultrareview](https://code.claude.com/docs/ko/ultrareview.md)를 위해 저장소를 git 번들로 패키징하여 업로드하는데, 브랜치나 다른 ref가 없는 저장소는 번들로 만들 수 없으므로 `/code-review ultra`와 `claude ultrareview` 하위 명령이 클라우드 세션 시작 전에 리뷰를 거부합니다.3880체크아웃에 커밋은 있지만 브랜치가 없을 수 있습니다. `git init`을 실행한 후 `git fetch <url>`과 `git checkout FETCH_HEAD`를 실행하면 ref가 없는 detached HEAD 상태가 됩니다. Claude Code는 [ultrareview](https://code.claude.com/docs/ko/ultrareview.md)를 위해 저장소를 git 번들로 패키징하여 업로드하는데, 브랜치나 다른 ref가 없는 저장소는 번들로 만들 수 없으므로 `/code-review ultra`와 `claude ultrareview` 하위 명령은 클라우드 세션이 시작되기 전에 리뷰를 거부합니다.
3793 3881
3794```text theme={null}3882```text theme={null}
3795Your checkout has no branches (detached HEAD only), which cloud review can't bundle. Create one first — `git checkout -b <name>` — then rerun /code-review ultra.3883Your checkout has no branches (detached HEAD only), which cloud review can't bundle. Create one first — `git checkout -b <name>` — then rerun /code-review ultra.
3796```3884```
3797 3885
3798v2.1.221 이전에는 Claude Code가 이 체크아웃에서 추적 중인 모든 파일을 리뷰하려고 시도했고 업로드가 실패했습니다.3886v2.1.221 이전에는 Claude Code가 이 체크아웃에서 추적되는 모든 파일을 리뷰하려고 시도했으며, 업로드가 실패했습니다.
3799 3887
3800**해결 방법:**3888**해결 방법:**
3801 3889
3802* `git checkout -b <name>`으로 현재 커밋에서 브랜치를 만든 다음 리뷰를 다시 실행합니다3890* `git checkout -b <name>`으로 현재 커밋에 브랜치를 만든 다음 리뷰를 다시 실행합니다
3803 3891
3804### Claude 계정에 연결된 GitHub 계정이 없음3892### No GitHub account is connected to your Claude account
3805 3893
3806`/code-review ultra <PR#>` 또는 `claude ultrareview <PR#>`를 실행하면 Claude Code는 클라우드 세션을 만들기 전에 [Claude 계정에 연결된 GitHub 계정](https://code.claude.com/docs/ko/ultrareview.md#review-a-pull-request)이 PR의 저장소에 접근할 수 있는지 서버에 확인합니다. 연결된 계정이 없거나 연결이 만료되어 클라우드 클론이 실패할 것이므로 Claude Code가 실행을 거부합니다. 거부된 실행에 대해서는 무료 실행 횟수를 사용하거나 사용량 크레딧을 청구하지 않습니다.3894`/code-review ultra <PR#>` 또는 `claude ultrareview <PR#>`을 실행하면, Claude Code는 클라우드 세션을 만들기 전에 [Claude 계정에 연결된 GitHub 계정](https://code.claude.com/docs/ko/ultrareview.md#review-a-pull-request)이 PR의 저장소에 접근할 수 있는지 서버에 확인합니다. 연결된 계정이 없거나 연결이 만료된 경우 클라우드 클론이 실패할 것이므로 Claude Code는 실행을 거부합니다. 거부된 실행에 대해서는 무료 실행 횟수를 사용하지 않으며 사용량 크레딧도 청구하지 않습니다.
3807 3895
3808```text theme={null}3896```text theme={null}
3809Ultrareview clones <owner>/<repo> in the cloud with the GitHub account connected to your Claude account, and none is connected (or the connection expired). To fix: run /web-setup to reuse your GitHub CLI login, or connect an account at https://claude.ai/connect-github — then re-run /code-review ultra 1234 (allow a minute after connecting).3897Ultrareview clones <owner>/<repo> in the cloud with the GitHub account connected to your Claude account, and none is connected (or the connection expired). To fix: run /web-setup to reuse your GitHub CLI login, or connect an account at https://claude.ai/connect-github — then re-run /code-review ultra 1234 (allow a minute after connecting).
3810```3898```
3811 3899
3812세션에서 [`/web-setup`](https://code.claude.com/docs/ko/web-quickstart#connect-from-your-terminal)을 사용할 수 없으면 메시지에는 claude.ai 링크만 표시됩니다.3900세션에서 [`/web-setup`](https://code.claude.com/docs/ko/web-quickstart#connect-from-your-terminal)을 사용할 수 없는 경우 메시지에는 claude.ai 링크만 표시됩니다.
3813 3901
3814**해결 방법:**3902**해결 방법:**
3815 3903
3818 3906
3819v2.1.248 이전에는 Claude Code가 실행 전에 이를 확인하지 않았습니다.3907v2.1.248 이전에는 Claude Code가 실행 전에 이를 확인하지 않았습니다.
3820 3908
3821### 연결된 GitHub 계정이 저장소를 볼 수 없음3909### Your connected GitHub account can't see the repository
3822 3910
3823`/code-review ultra <PR#>` 또는 `claude ultrareview <PR#>`를 실행했지만 [Claude 계정에 연결된 GitHub 계정](https://code.claude.com/docs/ko/ultrareview.md#review-a-pull-request)이 PR의 저장소를 읽을 수 없어 클라우드 클론이 실패할 것이므로 Claude Code가 실행을 거부합니다. 거부된 실행에 대해서는 무료 실행 횟수를 사용하거나 사용량 크레딧을 청구하지 않습니다.3911`/code-review ultra <PR#>` 또는 `claude ultrareview <PR#>`을 실행했지만 [Claude 계정에 연결된 GitHub 계정](https://code.claude.com/docs/ko/ultrareview.md#review-a-pull-request)이 PR의 저장소를 읽을 수 없으므로, 클라우드 클론이 실패할 것이어서 Claude Code가 실행을 거부합니다. 거부된 실행에 대해서는 무료 실행 횟수를 사용하지 않으며 사용량 크레딧도 청구하지 않습니다.
3824 3912
3825```text theme={null}3913```text theme={null}
3826Your connected GitHub account can't see <owner>/<repo> — usually the Claude GitHub app isn't installed on <owner> or wasn't granted this repo (web-connected accounts need it for private repos), or a different GitHub account is connected. To fix: run /web-setup to reuse your GitHub CLI login, or install the app at https://github.com/apps/claude/installations/new — then re-run /code-review ultra 1234.3914Your connected GitHub account can't see <owner>/<repo> — usually the Claude GitHub app isn't installed on <owner> or wasn't granted this repo (web-connected accounts need it for private repos), or a different GitHub account is connected. To fix: run /web-setup to reuse your GitHub CLI login, or install the app at https://github.com/apps/claude/installations/new — then re-run /code-review ultra 1234.
3827```3915```
3828 3916
3829세션에서 [`/web-setup`](https://code.claude.com/docs/ko/web-quickstart#connect-from-your-terminal)을 사용할 수 없으면 메시지에는 앱 설치만 표시됩니다.3917세션에서 [`/web-setup`](https://code.claude.com/docs/ko/web-quickstart#connect-from-your-terminal)을 사용할 수 없는 경우 메시지에는 앱 설치만 표시됩니다.
3830 3918
3831**해결 방법:**3919**해결 방법:**
3832 3920
3833* 로컬 `gh` CLI가 저장소를 읽을 수 있다면 `/web-setup`을 실행하여 그 로그인을 Claude 계정에 연결합니다3921* 로컬 `gh` CLI가 저장소를 읽을 수 있다면 `/web-setup`을 실행하여 해당 로그인을 Claude 계정에 연결합니다
3834* 변경 후 리뷰를 다시 실행합니다3922* 변경한 후 리뷰를 다시 실행합니다
3835 3923
3836v2.1.248 이전에는 Claude Code가 실행 전에 이를 확인하지 않았습니다.3924v2.1.248 이전에는 Claude Code가 실행 전에 이를 확인하지 않았습니다.
3837 3925
3838### GitHub App 사전 검사가 일시적으로 실패함3926### The GitHub App preflight failed transiently
3839 3927
3840로컬 저장소에서 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)을 시작했는데 두 단계가 함께 실패했습니다. Claude Code가 저장소 번들을 빌드하거나 업로드할 수 없었습니다. 업로드 전에 Claude Code는 클라우드 서비스가 GitHub에서 저장소를 클론할 수 있는지 확인했는데, 이 확인이 명확한 답 대신 네트워크 오류, 시간 초과, 일시적인 서버 오류처럼 재시도하면 해소될 수 있는 오류로 끝났습니다. 전체 메시지는 `Could not upload repo bundle (<error>)`처럼 번들을 막은 원인으로 시작하고 사전 검사 문장으로 끝납니다:3928로컬 저장소에서 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)을 시작했는데 두 단계가 함께 실패했습니다. Claude Code가 저장소의 번들을 빌드하거나 업로드할 수 없었습니다. 업로드 전에 Claude Code는 클라우드 서비스가 GitHub에서 저장소를 클론할 수 있는지 확인했는데, 이 확인이 명확한 답을 얻지 못하고 네트워크 오류, 시간 초과, 일시적인 서버 오류처럼 재시도하면 해소될 수 있는 오류로 끝났습니다. 전체 메시지는 `Could not upload repo bundle (<error>)`처럼 번들을 중단시킨 원인으로 시작하고, 사전 확인 문장으로 끝납니다:
3841 3929
3842```text theme={null}3930```text theme={null}
3843Could not upload repo bundle (<error>). The GitHub App preflight failed transiently (network or service hiccup) — retry in a moment to start from GitHub instead3931Could not upload repo bundle (<error>). The GitHub App preflight failed transiently (network or service hiccup) — retry in a moment to start from GitHub instead
3845 3933
3846**해결 방법:**3934**해결 방법:**
3847 3935
3848* 잠시 후 명령을 다시 실행합니다. GitHub 확인이 통과하면 Claude Code가 GitHub 클론에서 세션을 시작할 수 있으므로 실패한 업로드가 더 이상 실행을 막지 않습니다3936* 잠시 후 명령을 다시 실행합니다. GitHub 확인이 통과하면 Claude Code가 GitHub 클론에서 세션을 시작할 수 있으므로, 실패한 업로드가 더 이상 실행을 막지 않습니다
3849* 재시도가 계속 실패하면 메시지 앞부분에 업로드를 막은 원인이 표시됩니다. 그 원인을 수정할 수 있다면 수정하여 로컬 저장소에서 세션을 시작할 수 있도록 합니다3937* 재시도가 계속 실패하면 메시지의 시작 부분에 업로드를 중단시킨 원인이 표시됩니다. 해당 원인이 직접 해결할 수 있는 것이라면 해결하여 세션이 로컬 저장소에서 시작될 수 있도록 합니다
3850 3938
3851v2.1.251 이전에는 GitHub 확인이 일시적으로만 실패한 경우에도 Claude Code가 메시지를 `Please set up GitHub on https://claude.ai/code`로 끝냈으며, 설정 조언으로는 일시적인 실패를 해결할 수 없었습니다.3939v2.1.251 이전에는 GitHub 확인이 일시적으로만 실패한 경우에도 Claude Code가 메시지를 `Please set up GitHub on https://claude.ai/code`로 끝냈는데, 설정 안내로는 일시적인 실패를 해결할 수 없습니다.
3852 3940
3853### 저장소 업로드가 git 설정을 따를 수 없음3941### The repository upload can't follow a git setting
3854 3942
3855[로컬 저장소를 업로드하는 클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md#send-local-repositories-without-github) 또는 브랜치의 [ultrareview](https://code.claude.com/docs/ko/ultrareview.md)를 시작했는데, 파일에 어떤 속성 규칙이 적용되는지 결정하는 git 설정 중 하나를 업로드가 따를 수 없습니다. 업로드가 진행되어 규칙을 놓치면, clean 필터로 암호화되는 파일처럼 git이 저장 전에 변환하는 파일이 디스크에 있는 그대로 클라우드에 전달될 수 있습니다. 따라서 Claude Code는 업로드를 거부하며 아무것도 업로드되지 않습니다:3943[로컬 저장소를 업로드하는 클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md#send-local-repositories-without-github) 또는 브랜치의 [ultrareview](https://code.claude.com/docs/ko/ultrareview.md)를 시작했는데, 파일에 적용되는 attribute 규칙을 결정하는 git 설정 중 하나를 업로드가 따를 수 없습니다. 업로드를 그대로 진행하여 규칙을 놓치면, clean 필터가 암호화하는 파일처럼 git이 저장 전에 변환하는 파일이 디스크에 있는 그대로 클라우드에 전송될 수 있습니다. 그래서 Claude Code는 업로드를 거부하며, 아무것도 업로드되지 않습니다:
3856 3944
3857```text theme={null}3945```text theme={null}
3858Not uploading this working tree: core.ignoreCase (which decides whether .gitattributes patterns match file names regardless of letter case) is set in <file>, and the upload cannot follow that setting, so a file git would change before storing it (to encrypt it, for example) could be uploaded as it is on disk. Move the core.ignoreCase line into this repository’s .git/config or directly into your ~/.gitconfig, then retry.3946Not uploading this working tree: core.ignoreCase (which decides whether .gitattributes patterns match file names regardless of letter case) is set in <file>, and the upload cannot follow that setting, so a file git would change before storing it (to encrypt it, for example) could be uploaded as it is on disk. Move the core.ignoreCase line into this repository’s .git/config or directly into your ~/.gitconfig, then retry.
3859```3947```
3860 3948
3861메시지에는 설정과 설정된 위치가 표시되며, 해당하는 경우에 대한 해결 방법으로 끝납니다. `core.attributesFile`과 `attr.tree`에 대해서도 각각의 해결 방법과 함께 같은 거부가 표시됩니다.3949메시지에는 해당 설정과 설정된 위치가 표시되며, 해당 사례에 맞는 해결 방법으로 끝납니다. `core.attributesFile`과 `attr.tree`에 대해서도 각각의 해결 방법과 함께 동일한 거부 메시지가 표시됩니다.
3862 3950
3863메시지에는 git 구성이 `include` 또는 `includeIf` 지시문을 통해 불러오는 설정 파일이 표시될 수 있으며, 해당 지시문의 조건이 이 저장소에 적용되지 않는 경우에도 마찬가지입니다.3951메시지에는 git 구성이 `include` 또는 `includeIf` 지시문을 통해 불러오는 설정 파일이 표시될 수 있으며, 이는 해당 지시문의 조건이 이 저장소에 적용되지 않는 경우에도 마찬가지입니다.
3864 3952
3865**해결 방법:**3953**해결 방법:**
3866 3954
3867* 메시지의 마지막 문장에 있는 해결 방법을 적용합니다3955* 메시지의 마지막 문장에 있는 해결 방법을 적용합니다
3868 3956
3869### GitHub가 Claude 계정에 연결되어 있지 않음3957### GitHub isn't connected to your Claude account
3870 3958
3871`/autofix-pr` 등을 사용하여 로컬 저장소에서 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)을 시작했습니다. Claude 계정에 연결된 GitHub 계정이 없거나 연결이 만료되었으므로 Claude Code가 실행을 거부합니다:3959예를 들어 `/autofix-pr`로 로컬 저장소에서 [클라우드 세션](https://code.claude.com/docs/ko/claude-code-on-the-web.md)을 시작했습니다. Claude 계정에 연결된 GitHub 계정이 없거나 연결이 만료되었으므로 Claude Code가 실행을 거부합니다:
3872 3960
3873```text theme={null}3961```text theme={null}
3874GitHub isn't connected to your Claude account, so this repository can't be cloned in the cloud. Run /web-setup to connect with your GitHub CLI login, or connect on the web at https://claude.ai/connect-github3962GitHub isn't connected to your Claude account, so this repository can't be cloned in the cloud. Run /web-setup to connect with your GitHub CLI login, or connect on the web at https://claude.ai/connect-github
3875```3963```
3876 3964
3877[`/schedule`](https://code.claude.com/docs/ko/routines)로 클라우드 예약 작업을 만들 때는 동일한 메시지가 저장소 이름이 포함된 설정 안내로 표시되며, 이 안내는 작업 생성을 막지 않습니다.3965[`/schedule`](https://code.claude.com/docs/ko/routines)로 클라우드 예약 작업을 만들 때는 동일한 메시지가 저장소 이름을 포함한 설정 안내로 표시되며, 이 안내는 작업 생성을 막지 않습니다.
3878 3966
3879**해결 방법:**3967**해결 방법:**
3880 3968
3881* `/web-setup`을 실행하여 GitHub CLI 로그인을 Claude 계정에 연결하거나, [claude.ai/connect-github](https://claude.ai/connect-github)에서 계정을 연결합니다. 두 방법의 차이는 [GitHub 인증 옵션](https://code.claude.com/docs/ko/claude-code-on-the-web.md#github-authentication-options)을 참조하십시오.3969* `/web-setup`을 실행하여 GitHub CLI 로그인을 Claude 계정에 연결하거나, [claude.ai/connect-github](https://claude.ai/connect-github)에서 계정을 연결합니다. 두 방법의 차이는 [GitHub 인증 옵션](https://code.claude.com/docs/ko/claude-code-on-the-web.md#github-authentication-options)을 참조하십시오.
3882* 연결하고 1분 후에 명령을 다시 실행합니다3970* 연결하고 1분 후에 명령을 다시 실행합니다
3883 3971
3884v2.1.268 이전에는 Claude Code가 이를 Claude GitHub App 확인의 일시적인 실패로 보고하고 재시도하거나 앱을 설치하도록 제안했지만, 둘 다 GitHub 계정을 연결하지 않습니다.3972v2.1.268 이전에는 Claude Code가 이를 Claude GitHub App 확인의 일시적인 실패로 보고하고 재시도나 앱 설치를 제안했지만, 어느 쪽도 GitHub 계정을 연결하지 않습니다.
3885 3973
3886### GitHub 조직 정책이 Claude를 차단하고 있음3974### A GitHub organization policy is blocking Claude
3887 3975
3888Claude Code 프롬프트에서 [`/autofix-pr`](https://code.claude.com/docs/ko/claude-code-on-the-web#auto-fix-pull-requests)처럼 클라우드 세션을 시작하는 명령을 실행했습니다. Claude Code는 세션을 생성하기 전에 GitHub에서 Claude의 저장소 접근 권한을 확인하는데, GitHub 조직에 Claude를 차단하는 정책이 있어 GitHub가 이를 거부했습니다. Claude Code는 그 시점에서 중단하고 해당 정책을 명시하는 메시지를 표시합니다.3976Claude Code 프롬프트에서 [`/autofix-pr`](https://code.claude.com/docs/ko/claude-code-on-the-web#auto-fix-pull-requests)처럼 클라우드 세션을 시작하는 명령을 실행했습니다. Claude Code는 세션을 만들기 전에 GitHub에서 Claude의 저장소 접근 권한을 확인하는데, GitHub 조직에 Claude를 차단하는 정책이 있어 GitHub가 이를 거부했습니다. Claude Code는 여기서 중단하고 해당 정책을 명시한 메시지를 표시합니다.
3889 3977
3890IP 허용 목록이 접근을 차단하는 경우 메시지는 다음과 같습니다.3978IP 허용 목록이 접근을 차단하는 경우 메시지는 다음과 같습니다:
3891 3979
3892```text theme={null}3980```text theme={null}
3893Your GitHub organization has an IP allowlist that is blocking Claude. Add Claude's IP ranges to your GitHub allowlist.3981Your GitHub organization has an IP allowlist that is blocking Claude. Add Claude's IP ranges to your GitHub allowlist.
3894```3982```
3895 3983
3896싱글 사인온이 차단하는 경우 메시지는 다음과 같습니다.3984싱글 사인온이 차단하는 경우 메시지는 다음과 같습니다:
3897 3985
3898```text theme={null}3986```text theme={null}
3899Your GitHub organization requires single sign-on. Disconnect and reconnect GitHub on the Connectors page in Claude on the web, click Authorize next to your organization when GitHub asks, then try again.3987Your GitHub organization requires single sign-on. Disconnect and reconnect GitHub on the Connectors page in Claude on the web, click Authorize next to your organization when GitHub asks, then try again.
3900```3988```
3901 3989
3902Microsoft Entra ID 조건부 액세스 정책이 차단하는 경우 메시지는 다음과 같습니다.3990Microsoft Entra ID 조건부 액세스 정책이 차단하는 경우 메시지는 다음과 같습니다:
3903 3991
3904```text theme={null}3992```text theme={null}
3905Your GitHub organization's identity provider (Microsoft Entra ID) has a Conditional Access policy that is blocking Claude. Ask your GitHub Enterprise or Entra ID admin to allow Claude in that policy.3993Your GitHub organization's identity provider (Microsoft Entra ID) has a Conditional Access policy that is blocking Claude. Ask your GitHub Enterprise or Entra ID admin to allow Claude in that policy.
3908**해결 방법:**3996**해결 방법:**
3909 3997
3910* **IP 허용 목록**: GitHub 조직 또는 엔터프라이즈의 소유자에게 Anthropic의 아웃바운드 IP 주소를 허용하도록 요청합니다. 주소와 변경할 GitHub 설정은 [GitHub 허용 목록 및 방화벽](https://code.claude.com/docs/ko/network-config.md#github-allow-lists-and-firewalls)을 참조하십시오.3998* **IP 허용 목록**: GitHub 조직 또는 엔터프라이즈의 소유자에게 Anthropic의 아웃바운드 IP 주소를 허용하도록 요청합니다. 주소와 변경할 GitHub 설정은 [GitHub 허용 목록 및 방화벽](https://code.claude.com/docs/ko/network-config.md#github-allow-lists-and-firewalls)을 참조하십시오.
3911* **싱글 사인온**: [claude.ai/customize/connectors](https://claude.ai/customize/connectors)에서 GitHub 연결을 해제한 다음 다시 연결합니다. GitHub가 요청하면 조직 옆의 **Authorize**를 클릭하여 새 연결이 해당 조직의 싱글 사인온에 대해 승인되도록 합니다.3999* **싱글 사인온**: [claude.ai/customize/connectors](https://claude.ai/customize/connectors)에서 GitHub 연결을 해제한 다음 다시 연결합니다. GitHub가 요청하면 조직 옆의 **Authorize**를 클릭하여 새 연결이 해당 조직의 싱글 사인온에 대해 인가되도록 합니다.
3912* **조건부 액세스 정책**: GitHub Enterprise 또는 Microsoft Entra ID 관리자에게 해당 정책에서 Claude를 허용하도록 요청합니다4000* **조건부 액세스 정책**: GitHub Enterprise 또는 Microsoft Entra ID 관리자에게 해당 정책에서 Claude를 허용하도록 요청합니다
3913* 변경 후 명령을 다시 실행합니다4001* 변경한 후 명령을 다시 실행합니다
3914 4002
3915### 싱글 사인온 승인 필요4003### Single sign-on authorization needed
3916 4004
3917[`/install-github-app`](https://code.claude.com/docs/ko/github-actions#quick-setup)을 실행하고 SAML 싱글 사인온을 적용하는 조직의 저장소를 선택했습니다. Claude Code는 설정 전에 GitHub CLI로 저장소 접근 권한을 확인하는데, `gh` 토큰이 아직 해당 조직에 대해 승인되지 않아 GitHub가 이 확인을 거부했습니다. 마법사는 승인 단계와 함께 경고를 표시합니다.4005[`/install-github-app`](https://code.claude.com/docs/ko/github-actions#quick-setup)을 실행하고 SAML 싱글 사인온을 적용하는 조직의 저장소를 선택했습니다. Claude Code는 설정 전에 GitHub CLI로 저장소에 대한 접근 권한을 확인하는데, `gh` 토큰이 아직 해당 조직에 대해 인가되지 않았기 때문에 GitHub가 이 확인을 거부했습니다. 마법사는 인가 단계와 함께 경고를 표시합니다:
3918 4006
3919```text theme={null}4007```text theme={null}
3920Single sign-on authorization needed4008Single sign-on authorization needed
3923 4011
3924**해결 방법:**4012**해결 방법:**
3925 4013
3926* `gh auth refresh -h github.com -s repo,workflow`를 실행하여 `repo` 및 `workflow` 범위로 GitHub CLI 로그인을 다시 승인하고, GitHub가 싱글 사인온을 요청하면 조직을 승인합니다4014* `gh auth refresh -h github.com -s repo,workflow`를 실행하여 `repo` 및 `workflow` 범위로 GitHub CLI 로그인을 다시 인가하고, GitHub가 싱글 사인온을 요청하면 조직을 인가합니다
3927* `GH_TOKEN`의 개인 액세스 토큰으로 인증하는 경우 [github.com/settings/tokens](https://github.com/settings/tokens)를 열고 토큰에서 **Configure SSO**를 선택한 다음 조직을 승인합니다4015* `GH_TOKEN`의 개인 액세스 토큰으로 인증하는 경우 [github.com/settings/tokens](https://github.com/settings/tokens)를 열고 토큰에서 **Configure SSO**를 선택한 다음 조직을 인가합니다
3928* `/install-github-app`을 다시 실행합니다4016* `/install-github-app`을 다시 실행합니다
3929 4017
3930v2.1.273 이전에는 이 상황에서 Claude Code가 대신 `Admin permissions required` 경고를 표시했습니다.4018v2.1.273 이전에는 이 상황에서 Claude Code가 대신 `Admin permissions required` 경고를 표시했습니다.
3931 4019
3932### 대화를 재개하지 못함4020### Failed to resume the conversation
3933 4021
3934Claude Code가 [`claude --resume` 선택기](https://code.claude.com/docs/ko/sessions#use-the-session-picker)에서 선택한 세션의 저장된 트랜스크립트를 읽거나 처리할 수 없어, 부분적으로 로드된 상태로 계속하는 대신 프로세스를 종료합니다. 메시지에는 재시도할 명령이 포함됩니다.4022Claude Code가 [`claude --resume` 선택기](https://code.claude.com/docs/ko/sessions#use-the-session-picker)에서 선택한 세션의 저장된 트랜스크립트를 읽거나 처리할 수 없어, 부분적으로 로드된 상태로 계속하는 대신 프로세스를 종료합니다. 메시지에는 재시도할 명령이 포함됩니다:
3935 4023
3936```text theme={null}4024```text theme={null}
3937Failed to resume the conversation.4025Failed to resume the conversation.
3938Run claude --resume <session-id> to retry, or claude to start a new session.4026Run claude --resume <session-id> to retry, or claude to start a new session.
3939```4027```
3940 4028
3941Claude Code는 메시지를 표시한 후 코드 1로 종료됩니다. 실행 중인 세션 내의 `/resume` 선택기는 대신 대화에 `Failed to resume conversation`을 보고하며, 현재 세션은 계속 실행됩니다. v2.1.216 이전에는 `claude --resume` 선택기에서 재개에 실패하면 이 메시지를 표시하는 대신 `Resuming conversation…` 스피너에 무기한 머물러 있었습니다.4029Claude Code는 메시지를 표시한 후 코드 1로 종료합니다. 실행 중인 세션 내의 `/resume` 선택기는 대신 대화에 `Failed to resume conversation`을 보고하며, 현재 세션은 계속 실행됩니다. v2.1.216 이전에는 `claude --resume` 선택기에서 재개가 실패하면 이 메시지를 표시하는 대신 `Resuming conversation…` 스피너에 무기한 머물렀습니다.
3942 4030
3943**해결 방법:**4031**해결 방법:**
3944 4032
3946* v2.1.285 이전 버전에서 재시도가 같은 방식으로 실패하면 `claude update`를 실행하고 다시 재개합니다. 해당 버전은 저장된 트랜스크립트에 읽을 수 없는 항목이 포함되어 있으면 재개에 실패합니다.4034* v2.1.285 이전 버전에서 재시도가 같은 방식으로 실패하면 `claude update`를 실행하고 다시 재개합니다. 해당 버전은 저장된 트랜스크립트에 읽을 수 없는 항목이 포함되어 있으면 재개에 실패합니다.
3947* 재시도가 다시 실패하면 `claude`를 실행하여 새 세션을 시작합니다4035* 재시도가 다시 실패하면 `claude`를 실행하여 새 세션을 시작합니다
3948 4036
3949### 해당 세션 ID의 대화를 찾을 수 없음4037### No conversation found with the session ID
3950 4038
3951`claude --resume <session-id>`에 세션 ID를 전달했지만 일치하는 저장된 트랜스크립트가 없습니다.4039`claude --resume <session-id>`에 세션 ID를 전달했지만 일치하는 저장된 트랜스크립트가 없습니다:
3952 4040
3953```text theme={null}4041```text theme={null}
3954No conversation found with session ID: <session-id>4042No conversation found with session ID: <session-id>
3955```4043```
3956 4044
3957Claude Code는 메시지를 표시한 후 코드 1로 종료합니다. Claude Code는 [현재 프로젝트를 먼저 검색한 다음 이 머신의 다른 모든 프로젝트](https://code.claude.com/docs/ko/sessions.md#where-the-session-picker-looks)에서 ID를 찾습니다. v2.1.223 이전에는 조회가 현재 프로젝트 디렉터리와 해당 git worktree에서 멈췄으므로, 세션이 마지막으로 작업한 디렉터리에서 재개해야 합니다.4045Claude Code는 메시지를 표시한 후 코드 1로 종료합니다. Claude Code는 [현재 프로젝트를 먼저 검색한 다음 이 머신의 다른 모든 프로젝트](https://code.claude.com/docs/ko/sessions.md#where-the-session-picker-looks)에서 ID를 검색합니다. v2.1.223 이전에는 현재 프로젝트 디렉터리와 해당 git worktree에서만 검색했으므로, 세션이 마지막으로 작업한 디렉터리에서 재개해야 했습니다.
3958 4046
3959일반적인 원인:4047일반적인 원인:
3960 4048
3961* **잘못 입력한 ID**: 비대화형 실행의 경우 ID는 [`--output-format json` 출력](https://code.claude.com/docs/ko/headless#get-structured-output)의 `session_id` 필드입니다4049* **잘못 입력한 ID**: 비대화형 실행의 경우 ID는 [`--output-format json` 출력](https://code.claude.com/docs/ko/headless#get-structured-output)의 `session_id` 필드입니다
3962* **삭제된 트랜스크립트**: Claude Code는 [보존 정리 규칙](https://code.claude.com/docs/ko/claude-directory.md#cleaned-up-automatically)에 따라 [보존 기간](https://code.claude.com/docs/ko/sessions.md#where-transcripts-are-stored)(기본값 30일)이 지나면 트랜스크립트를 제거합니다4050* **삭제된 트랜스크립트**: Claude Code는 [보존 정리 규칙](https://code.claude.com/docs/ko/claude-directory.md#cleaned-up-automatically)에 따라 [보존 기간](https://code.claude.com/docs/ko/sessions.md#where-transcripts-are-stored)(기본값 30일)이 지나면 트랜스크립트를 제거합니다
3963* **다른 머신**: Claude Code는 트랜스크립트를 로컬에 저장하므로 세션이 실행된 머신에서 재개해야 합니다4051* **다른 머신**: Claude Code는 트랜스크립트를 로컬에 저장하므로, 세션이 실행된 머신에서 재개해야 합니다
3964* **중복 사본**: `~/.claude/projects` 아래의 프로젝트 디렉터리를 복사하여 두 트랜스크립트가 같은 ID를 갖게 된 경우, Claude Code는 임의로 한 사본을 재개하는 대신 이 메시지를 보고합니다4052* **중복 사본**: `~/.claude/projects` 아래의 프로젝트 디렉터리를 복사하여 두 트랜스크립트가 같은 ID를 가지게 된 경우, Claude Code는 임의로 한 사본을 재개하지 않고 이 메시지를 보고합니다
3965 4053
3966**해결 방법:**4054**해결 방법:**
3967 4055
3968* 대화형 세션의 경우 `claude --resume`으로 [세션 선택기](https://code.claude.com/docs/ko/sessions.md#use-the-session-picker)를 열고 `Ctrl+A`를 눌러 이 머신의 모든 프로젝트로 범위를 넓힌 다음 세션을 선택합니다4056* 대화형 세션의 경우 `claude --resume`으로 [세션 선택기](https://code.claude.com/docs/ko/sessions.md#use-the-session-picker)를 열고 `Ctrl+A`를 눌러 이 머신의 모든 프로젝트로 범위를 넓힌 다음 세션을 선택합니다
3969* `claude -p` 또는 [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/overview.md)로 생성된 세션은 선택기에 나타나지 않으므로, 원래 실행에서 출력된 `session_id`와 ID를 다시 대조합니다4057* `claude -p` 또는 [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/overview.md)로 만든 세션은 선택기에 나타나지 않으므로, 원래 실행에서 출력된 `session_id`와 ID를 다시 대조합니다
3970 4058
3971### Claude Code가 이 세션의 트랜스크립트 파일을 읽을 때 Windows가 오류(EBADF)를 보고함4059### Windows reported an error (EBADF) when Claude Code read this session's transcript file
3972 4060
3973Windows에서 세션을 재개했고, 저장된 [트랜스크립트 파일](https://code.claude.com/docs/ko/sessions.md#where-transcripts-are-stored)은 정상적으로 열렸지만 이후 읽기가 시스템 오류 EBADF로 실패했습니다. 시스템 오류는 읽기가 실패한 이유를 알려주지 않으므로, 메시지에서 가능한 원인과 시도할 방법을 제안합니다.4061Windows에서 세션을 재개했는데, 저장된 [트랜스크립트 파일](https://code.claude.com/docs/ko/sessions.md#where-transcripts-are-stored)이 정상적으로 열린 후 읽기가 시스템 오류 EBADF로 실패했습니다. 시스템 오류는 읽기가 실패한 이유를 알려주지 않으므로, 메시지는 가능성 있는 원인과 시도해 볼 방법을 제안합니다:
3974 4062
3975```text theme={null}4063```text theme={null}
3976Windows reported an error (EBADF) when Claude Code read this session's transcript file, although the file had opened normally. This can happen when other software intercepts file reads — security, encryption or endpoint-management tools, for example. If it keeps happening for this conversation, try excluding the folder that holds Claude Code's session transcripts from such software (the .claude folder in your user profile, unless the app or CLAUDE_CONFIG_DIR points Claude Code elsewhere), or adding Claude Code to its allowed applications, then resume again.4064Windows reported an error (EBADF) when Claude Code read this session's transcript file, although the file had opened normally. This can happen when other software intercepts file reads — security, encryption or endpoint-management tools, for example. If it keeps happening for this conversation, try excluding the folder that holds Claude Code's session transcripts from such software (the .claude folder in your user profile, unless the app or CLAUDE_CONFIG_DIR points Claude Code elsewhere), or adding Claude Code to its allowed applications, then resume again.
3977```4065```
3978 4066
3979이 메시지는 `Failed to resume session <session-id>`처럼 명령 자체의 실패 줄 다음에 표시됩니다. `claude --resume` 또는 [`claude -p`](https://code.claude.com/docs/ko/headless) 명령은 이를 표시한 후 코드 1로 종료됩니다. 세션 내에서 `/resume`을 실행한 경우에는 현재 세션이 계속 실행됩니다.4067이 메시지는 `Failed to resume session <session-id>`와 같은 명령 자체의 실패 줄 뒤에 표시됩니다. `claude --resume` 또는 [`claude -p`](https://code.claude.com/docs/ko/headless) 명령은 메시지를 표시한 후 코드 1로 종료합니다. 세션 내에서 `/resume`을 실행한 경우에는 현재 세션이 계속 실행됩니다.
3980 4068
3981**해결 방법:**4069**해결 방법:**
3982 4070
3983* 보안, 암호화 또는 엔드포인트 관리 도구처럼 파일 읽기를 검사하거나 가로채는 소프트웨어에서 세션 트랜스크립트가 있는 폴더를 제외합니다. 트랜스크립트는 기본적으로 `%USERPROFILE%\.claude\projects` 아래에 있거나, [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/ko/env-vars)이 지정하는 디렉터리 아래에 있습니다4071* 보안, 암호화, 엔드포인트 관리 도구처럼 파일 읽기를 검사하거나 가로채는 소프트웨어에서 세션 트랜스크립트가 저장된 폴더를 제외합니다. 트랜스크립트는 기본적으로 `%USERPROFILE%\.claude\projects` 아래에 있거나, [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/ko/env-vars)가 지정하는 디렉터리 아래에 있습니다
3984* 제외를 추가할 수 없는 경우 대신 해당 소프트웨어의 허용된 애플리케이션에 Claude Code를 추가합니다4072* 제외 항목을 추가할 수 없다면, 대신 해당 소프트웨어의 허용된 애플리케이션에 Claude Code를 추가합니다
3985* 세션을 다시 재개합니다4073* 세션을 다시 재개합니다
3986 4074
3987v2.1.282 이전에는 실패 시 아무런 설명이 없었습니다. `claude --resume <session-id>`는 `Failed to resume session <session-id>`로 끝났고, `-p` 실행은 `Failed to resume session: EBADF: bad file descriptor, read`처럼 시스템 오류 텍스트만 출력했습니다.4075v2.1.282 이전에는 실패에 대한 설명이 없었습니다. `claude --resume <session-id>`는 `Failed to resume session <session-id>`에서 끝났고, `-p` 실행은 `Failed to resume session: EBADF: bad file descriptor, read`와 같은 시스템 오류 텍스트만 출력했습니다.
3988 4076
3989### 이 세션에서 렌더러를 전환할 수 없음4077### Cannot switch renderers in this session
3990 4078
3991렌더러를 전환하면 Claude Code는 프로세스를 다시 시작합니다. Claude Code가 다시 시작을 거부하는 세션에서 [`/tui`](https://code.claude.com/docs/ko/fullscreen#enable-fullscreen-rendering)를 실행했으므로, 전환하지 않고 아무것도 저장하지 않습니다. 표시되는 메시지로 원인을 알 수 있습니다.4079렌더러를 전환하면 Claude Code는 프로세스를 다시 시작합니다. Claude Code가 다시 시작하기를 거부하는 세션에서 [`/tui`](https://code.claude.com/docs/ko/fullscreen#enable-fullscreen-rendering)를 실행했으므로, 전환하지 않으며 아무것도 저장하지 않습니다. 표시되는 메시지로 원인을 알 수 있습니다:
3992 4080
3993* `Cannot switch renderers while work is running in the background`: 백그라운드 셸이나 서브에이전트처럼 다시 시작하면 중단될 백그라운드 작업이 실행 중입니다. 작업이 끝날 때까지 기다리거나 [`/tasks`](https://code.claude.com/docs/ko/commands)로 중지한 다음 `/tui fullscreen` 또는 `/tui default`를 다시 실행합니다4081* `Cannot switch renderers while work is running in the background`: 백그라운드 셸이나 서브에이전트처럼 다시 시작하면 중단될 백그라운드 작업이 실행 중입니다. 작업이 끝날 때까지 기다리거나 [`/tasks`](https://code.claude.com/docs/ko/commands)로 중지한 다음 `/tui fullscreen` 또는 `/tui default`를 다시 실행합니다
3994* `Cannot switch renderers in this session`: 세션에 Claude Code가 다시 시작된 프로세스로 전달할 수 없는 제한이 있습니다. v2.1.234 이전에는 Claude Code가 그래도 다시 시작했고, 다시 실행된 세션은 해당 제한 없이 실행되었습니다4082* `Cannot switch renderers in this session`: 세션에 Claude Code가 다시 시작된 프로세스로 전달할 수 없는 제한이 있습니다. v2.1.234 이전에는 Claude Code가 그래도 다시 시작했고, 다시 실행된 세션은 해당 제한 없이 실행되었습니다
3995 4083
3996제한 메시지에서 괄호 안의 부분은 Claude Code가 발견한 제한을 나타냅니다.4084제한 관련 메시지에서 괄호 안의 부분은 Claude Code가 발견한 제한을 나타냅니다:
3997 4085
3998```text theme={null}4086```text theme={null}
3999Cannot switch renderers in this session — it has restrictions a restart can't carry over (permission rules set for this session only). Nothing was changed. Running /tui fullscreen in a session started without them switches every later session too.4087Cannot switch renderers in this session — it has restrictions a restart can't carry over (permission rules set for this session only). Nothing was changed. Running /tui fullscreen in a session started without them switches every later session too.
4000```4088```
4001 4089
4002메시지의 괄호 안에 표시될 수 있는 각 이유는 다음과 같습니다.4090메시지의 괄호 안에 표시될 수 있는 각 이유:
4003 4091
4004* `launch flags: a custom system prompt, a tool allowlist, or restricted settings`: Claude Code가 다시 시작된 프로세스로 다시 전달하지 않는 플래그로 세션을 시작했습니다. 이러한 플래그에는 [`--system-prompt`](https://code.claude.com/docs/ko/cli-reference#cli-flags), `--system-prompt-file`, `--append-system-prompt-file`, [`--tools`](https://code.claude.com/docs/ko/cli-reference#cli-flags) 허용 목록, [`--setting-sources`](https://code.claude.com/docs/ko/cli-reference#cli-flags), [`--permission-prompt-tool`](https://code.claude.com/docs/ko/cli-reference#cli-flags)이 포함됩니다4092* `launch flags: a custom system prompt, a tool allowlist, or restricted settings`: Claude Code가 다시 시작된 프로세스로 다시 전달하지 않는 플래그로 세션을 시작했습니다. 이러한 플래그에는 [`--system-prompt`](https://code.claude.com/docs/ko/cli-reference#cli-flags), `--system-prompt-file`, `--append-system-prompt-file`, [`--tools`](https://code.claude.com/docs/ko/cli-reference#cli-flags) 허용 목록, [`--setting-sources`](https://code.claude.com/docs/ko/cli-reference#cli-flags), [`--permission-prompt-tool`](https://code.claude.com/docs/ko/cli-reference#cli-flags)이 포함됩니다
4005* `permission rules set for this session only`: 훅 또는 SDK 호출자의 [권한 업데이트](https://code.claude.com/docs/ko/hooks.md#permission-update-entries)가 `session` 대상으로 거부 또는 확인 규칙을 추가했습니다. 세션 범위의 허용 규칙은 거부를 유발하지 않습니다. 다시 시작하면 해당 규칙이 삭제되고 Claude Code가 대신 다시 확인을 요청합니다4093* `permission rules set for this session only`: 훅이나 SDK 호출자의 [권한 업데이트](https://code.claude.com/docs/ko/hooks.md#permission-update-entries)가 `session` 대상으로 거부 또는 확인 규칙을 추가했습니다. 세션 범위의 허용 규칙은 거부를 유발하지 않습니다. 다시 시작하면 허용 규칙이 사라지고, Claude Code가 대신 다시 확인을 요청합니다
4006* `ask-before-running rules with no command-line form`: 훅 또는 SDK 호출자의 권한 업데이트가 Claude Code가 `--allowed-tools` 및 `--disallowed-tools`로 다시 전달하는 규칙과 함께 확인 규칙을 추가했습니다. 확인 규칙에 대한 플래그는 존재하지 않습니다4094* `ask-before-running rules with no command-line form`: 훅이나 SDK 호출자의 권한 업데이트가 Claude Code가 `--allowed-tools` 및 `--disallowed-tools`로 다시 전달하는 규칙과 함께 확인 규칙을 추가했습니다. 확인 규칙에 해당하는 플래그는 없습니다
4007* `permission rules a command line cannot carry intact` 및 `added directories a command line cannot carry intact`: 권한 업데이트가 세션 도중에 규칙이나 디렉터리 경로를 추가했습니다. 다시 시작된 프로세스의 명령줄은 해당 텍스트를 동일한 값으로 전달할 수 없습니다4095* `permission rules a command line cannot carry intact` 및 `added directories a command line cannot carry intact`: 권한 업데이트가 세션 도중에 규칙 또는 디렉터리 경로를 추가했습니다. 다시 시작된 프로세스의 명령줄은 해당 텍스트를 같은 값으로 전달할 수 없습니다
4008 4096
4009**해결 방법:**4097**해결 방법:**
4010 4098
4011* 해당 제한 없이 시작된 세션에서 `/tui fullscreen`을 실행하거나, 다시 전환하려면 `/tui default`를 실행합니다. Claude Code는 그곳에서 [`tui` 설정](https://code.claude.com/docs/ko/settings-reference#tui)을 저장합니다4099* 이러한 제한 없이 시작된 세션에서 `/tui fullscreen`을 실행하거나, 다시 전환하려면 `/tui default`를 실행합니다. Claude Code는 해당 세션에서 [`tui` 설정](https://code.claude.com/docs/ko/settings-reference#tui)을 저장합니다
4012 4100
4013### Can't restart while work is running or Remote Control is connected4101### Can't restart while work is running or Remote Control is connected
4014 4102
4015Claude Code가 다시 시작되지 않았으며 세션은 그대로 계속 실행됩니다. 메시지의 해결 방법을 따르세요.4103Claude Code가 다시 시작되지 않았으며, 세션은 그대로 계속 실행됩니다. 메시지에 있는 해결 방법을 따르십시오.
4016 4104
4017### Claude Code couldn't restart4105### Claude Code couldn't restart
4018 4106
4019이 메시지에 대화가 저장되었다고 표시되면, 대화는 디스크에 있으며 중단된 지점부터 이어서 진행할 수 있습니다. Claude Code가 자체적으로 다시 시작하는 중이었는데(예: [`/tui`](https://code.claude.com/docs/ko/fullscreen#enable-fullscreen-rendering)를 실행한 후 전체 화면 렌더링으로 전환하거나 해제하기 위해), 새 프로세스를 시작할 수 없어 상태 1로 종료되었습니다:4107이 메시지에 대화가 저장되었다고 표시되면, 대화는 디스크에 있으며 중단된 지점부터 이어서 진행할 수 있습니다. Claude Code가 예를 들어 [`/tui`](https://code.claude.com/docs/ko/fullscreen#enable-fullscreen-rendering)를 실행한 후 전체 화면 렌더링으로 전환하거나 해제하기 위해 스스로 다시 시작하던 중 새 프로세스를 시작하지 못하여 상태 1로 종료했습니다:
4020 4108
4021```text theme={null}4109```text theme={null}
4022Claude Code couldn't restart. Your conversation is saved. Start Claude Code again and run /resume to pick it up.4110Claude Code couldn't restart. Your conversation is saved. Start Claude Code again and run /resume to pick it up.
4023```4111```
4024 4112
4025다시 시작할 때 다시 열 대화가 없었던 경우(예: 새 세션에서 `/tui`가 첫 입력이었던 경우) 메시지는 `Claude Code couldn't restart. Start Claude Code again.`입니다.4113예를 들어 `/tui`가 새 세션의 첫 입력이었기 때문에 다시 시작할 때 다시 열 대화가 없었던 경우, 메시지는 `Claude Code couldn't restart. Start Claude Code again.`입니다.
4026 4114
4027**해결 방법:**4115**해결 방법:**
4028 4116
4029* 셸에서 `claude`를 다시 실행합니다. 메시지에 대화가 저장되었다고 표시되었다면 새 세션에서 [`/resume`](https://code.claude.com/docs/ko/sessions#resume-a-session)을 실행하고 해당 대화를 선택합니다. 목록에 없으면 [세션 선택기의 범위를 넓힙니다](https://code.claude.com/docs/ko/sessions.md#where-the-session-picker-looks)4117* 셸에서 `claude`를 다시 실행합니다. 메시지에 대화가 저장되었다고 표시되었다면, 새 세션에서 [`/resume`](https://code.claude.com/docs/ko/sessions#resume-a-session)을 실행하고 대화를 선택합니다. 목록에 없다면 [세션 선택기의 범위를 넓힙니다](https://code.claude.com/docs/ko/sessions.md#where-the-session-picker-looks)
4030* 다시 시작이 계속 실패하면 셸에서 [`claude --debug-file claude-debug.log`](https://code.claude.com/docs/ko/cli-reference#cli-flags)로 Claude Code를 시작합니다. 해당 세션에서 다시 시작이 실패하면, 시작한 디렉터리의 `claude-debug.log`에 운영 체제의 오류와 함께 `Failed to relaunch:` 줄이 기록됩니다. [문제를 보고](#report-an-error)할 때 해당 줄을 포함하십시오4118* 다시 시작이 계속 실패하면 셸에서 [`claude --debug-file claude-debug.log`](https://code.claude.com/docs/ko/cli-reference#cli-flags)로 Claude Code를 시작합니다. 해당 세션에서 다시 시작이 실패하면, 시작한 디렉터리의 `claude-debug.log`에 운영 체제의 오류가 포함된 `Failed to relaunch:` 줄이 기록됩니다. [문제를 보고](#report-an-error)할 때 해당 줄을 포함하십시오
4031 4119
4032### Claude Desktop을 열 수 없음4120### Couldn't open Claude Desktop
4033 4121
4034세션에서 [`/desktop`](https://code.claude.com/docs/ko/desktop#coming-from-the-cli) 또는 그 별칭인 `/app`을 실행했거나, 셸에서 [`claude --desktop`](https://code.claude.com/docs/ko/cli-reference#cli-flags)을 실행했는데 Claude Code가 Claude Desktop을 열기 위해 사용하는 시스템 명령이 실패했습니다. `/desktop` 이후에는 세션이 터미널에 유지되며, `claude --desktop`은 `Error:` 접두사 없이 메시지를 출력하고 상태 1로 종료됩니다.4122세션에서 [`/desktop`](https://code.claude.com/docs/ko/desktop#coming-from-the-cli) 또는 그 별칭인 `/app`을 실행했거나 셸에서 [`claude --desktop`](https://code.claude.com/docs/ko/cli-reference#cli-flags)을 실행했는데, Claude Code가 Claude Desktop을 여는 데 사용하는 시스템 명령이 실패했습니다. `/desktop` 후에는 세션이 터미널에 그대로 유지됩니다. `claude --desktop`은 `Error:` 접두사 없이 메시지를 출력하고 상태 1로 종료합니다.
4035 4123
4036괄호 안의 텍스트는 실패한 명령을 나타내며, 종료 상태와 오류 출력의 첫 줄이 생성된 경우 함께 표시합니다. macOS에서는 이 예시처럼 해당 명령이 `open`이며, Windows에서는 `rundll32`입니다.4124괄호 안의 텍스트는 실패한 명령을 나타내며, 종료 상태와 오류 출력의 첫 줄이 있는 경우 함께 표시됩니다. macOS에서는 이 예시처럼 해당 명령이 `open`이며, Windows에서는 `rundll32`입니다:
4037 4125
4038```text theme={null}4126```text theme={null}
4039Error: Couldn't open Claude Desktop (`open` exited 1: LSOpenURLsWithRole() failed for the URL claude://resume?session=<session-id> with error -10814). Open Claude Desktop and try again.4127Error: Couldn't open Claude Desktop (`open` exited 1: LSOpenURLsWithRole() failed for the URL claude://resume?session=<session-id> with error -10814). Open Claude Desktop and try again.
4044* Claude Desktop을 직접 연 다음 `/desktop` 또는 `claude --desktop`을 다시 실행합니다4132* Claude Desktop을 직접 연 다음 `/desktop` 또는 `claude --desktop`을 다시 실행합니다
4045* 실패한 명령의 전체 오류 출력을 확인하려면 `/debug`로 디버그 로깅을 켜고 `/desktop`을 다시 실행하거나, `claude --desktop --debug-file <path>`를 실행한 다음 디버그 로그를 확인합니다4133* 실패한 명령의 전체 오류 출력을 확인하려면 `/debug`로 디버그 로깅을 켜고 `/desktop`을 다시 실행하거나, `claude --desktop --debug-file <path>`를 실행한 다음 디버그 로그를 확인합니다
4046 4134
4047v2.1.285 이전에는 메시지가 `Open Claude Desktop and run /desktop again.`으로 끝났습니다. v2.1.275 이전에는 `Failed to open Claude Desktop. Please try opening it manually.`였으며 무엇이 실패했는지 알려주지 않았습니다.4135v2.1.285 이전에는 메시지가 `Open Claude Desktop and run /desktop again.`으로 끝났습니다. v2.1.275 이전에는 메시지가 `Failed to open Claude Desktop. Please try opening it manually.`였으며 무엇이 실패했는지 알려주지 않았습니다.
4048 4136
4049### /terminal-setup이 Zed 키맵을 변경하지 않음4137### /terminal-setup left your Zed keymap unchanged
4050 4138
4051Zed에서 [`/terminal-setup`](https://code.claude.com/docs/ko/terminal-config#enter-multiline-prompts)을 실행했지만 Claude Code가 Zed `keymap.json` 업데이트를 완료할 수 없어 파일을 그대로 두었습니다.4139Zed에서 [`/terminal-setup`](https://code.claude.com/docs/ko/terminal-config#enter-multiline-prompts)을 실행했는데, Claude Code가 Zed `keymap.json` 업데이트를 완료할 수 없어 파일을 그대로 두었습니다.
4052 4140
4053각 메시지는 키맵 경로를 명시하고, 직접 추가할 키보드 단축키 블록으로 끝납니다.4141각 메시지에는 키맵 경로가 표시되며, 직접 추가할 키보드 단축키 블록으로 끝납니다:
4054 4142
4055```text theme={null}4143```text theme={null}
4056Couldn't update your Zed keymap, so it was left unchanged.4144Couldn't update your Zed keymap, so it was left unchanged.
4058{ "context": "Terminal", "bindings": { "shift-enter": ["terminal::SendText", "\u001b\r"] } }4146{ "context": "Terminal", "bindings": { "shift-enter": ["terminal::SendText", "\u001b\r"] } }
4059```4147```
4060 4148
4061메시지의 첫 줄은 원인을 나타냅니다.4149메시지의 첫 줄에 원인이 표시됩니다:
4062 4150
4063* `Couldn't read your Zed keymap, so it was left unchanged.`: 파일 권한 등의 이유로 Claude Code가 파일을 읽을 수 없었습니다4151* `Couldn't read your Zed keymap, so it was left unchanged.`: 파일 권한 등의 이유로 Claude Code가 파일을 읽을 수 없었습니다
4064* `Your Zed keymap isn't a readable list of keybindings, so it was left unchanged.`: 파일은 정상적으로 읽었지만, `//` 주석과 후행 쉼표를 허용하더라도 키보드 단축키 블록의 배열로 파싱되지 않습니다4152* `Your Zed keymap isn't a readable list of keybindings, so it was left unchanged.`: 파일은 정상적으로 읽었지만, `//` 주석과 후행 쉼표를 허용하더라도 키보드 단축키 블록의 배열로 파싱되지 않습니다
4065* `Couldn't back up your Zed keymap; not modifying it.`: Claude Code가 파일 옆에 `.bak` 백업으로 복사할 수 없어 아무것도 변경하지 않았습니다4153* `Couldn't back up your Zed keymap; not modifying it.`: Claude Code가 파일을 옆에 있는 `.bak` 백업으로 복사할 수 없었으므로 아무것도 변경하지 않았습니다
4066* `Couldn't update your Zed keymap, so it was left unchanged.`: 병합된 결과가 해당 바인딩을 포함하는 유효한 키맵으로 검증되지 않아 Claude Code가 쓰지 않고 폐기했습니다. 키가 중복된 키보드 단축키 블록이 원인일 수 있습니다4154* `Couldn't update your Zed keymap, so it was left unchanged.`: 병합된 결과가 해당 단축키를 포함한 유효한 키맵으로 확인되지 않아, Claude Code가 쓰지 않고 폐기했습니다. 중복된 키가 있는 키보드 단축키 블록이 원인일 수 있습니다
4067 4155
4068**해결 방법:**4156**해결 방법:**
4069 4157
4070* 메시지의 블록을 메시지가 명시하는 경로의 `keymap.json` 최상위 배열에 복사합니다4158* 메시지에 있는 블록을 복사하여 메시지에 표시된 경로의 `keymap.json` 최상위 배열에 추가합니다
4071* `isn't a readable list of keybindings`의 경우 구문 오류를 수정하거나 파일의 최상위 값을 배열로 만든 다음 `/terminal-setup`을 다시 실행합니다4159* `isn't a readable list of keybindings`의 경우 구문 오류를 수정하거나 파일의 최상위 값을 배열로 만든 다음 `/terminal-setup`을 다시 실행합니다
4072 4160
4073v2.1.247 이전에는 `/terminal-setup`이 `//` 주석이나 후행 쉼표를 사용하는 Zed 키맵을 파싱할 수 없었으며, 바인딩이 설치되었다고 보고하면서 전체 파일을 자체 바인딩만으로 대체했습니다. 이전 버전이 대체한 키맵을 복원하려면 [여러 줄 프롬프트 입력](https://code.claude.com/docs/ko/terminal-config.md#enter-multiline-prompts)에 설명된 `.bak` 백업 파일을 사용하십시오.4161v2.1.247 이전에는 `/terminal-setup`이 `//` 주석이나 후행 쉼표를 사용하는 Zed 키맵을 파싱할 수 없었으며, 전체 파일을 자체 단축키만 포함하도록 교체하면서 단축키가 설치되었다고 보고했습니다. 이전 버전이 교체한 키맵을 복원하려면 [여러 줄 프롬프트 입력](https://code.claude.com/docs/ko/terminal-config.md#enter-multiline-prompts)에 설명된 `.bak` 백업 파일을 사용하십시오.
4074 4162
4075### 이 연결에서는 스킬 사용 보고서를 사용할 수 없음4163### Skill usage reports are not available on this connection
4076 4164
4077휴대폰이나 브라우저에서 [Remote Control](https://code.claude.com/docs/ko/remote-control.md)을 통해 [`/skill-doctor`](https://code.claude.com/docs/ko/skills#find-unused-skills)를 실행했습니다. Claude Code는 Remote Control을 통해 스킬 사용 보고서를 보내지 않으며, 대신 다음 메시지로 응답합니다.4165휴대폰이나 브라우저에서 [Remote Control](https://code.claude.com/docs/ko/remote-control.md)을 통해 [`/skill-doctor`](https://code.claude.com/docs/ko/skills#find-unused-skills)를 실행했습니다. Claude Code는 Remote Control을 통해 스킬 사용 보고서를 보내지 않으며, 대신 다음 메시지로 응답합니다:
4078 4166
4079```text theme={null}4167```text theme={null}
4080Skill usage reports are not available on this connection.4168Skill usage reports are not available on this connection.
4084 4172
4085* 세션이 실행 중인 머신의 터미널에서 `/skill-doctor`를 실행하거나, 해당 머신에서 `claude -p "/skill-doctor"`를 실행합니다4173* 세션이 실행 중인 머신의 터미널에서 `/skill-doctor`를 실행하거나, 해당 머신에서 `claude -p "/skill-doctor"`를 실행합니다
4086 4174
4087### Remote Control을 통해서는 사용자 지정 출력 스타일을 선택할 수 없음4175### Custom output styles can't be selected over Remote Control
4088 4176
4089[Remote Control](https://code.claude.com/docs/ko/remote-control.md)을 통해 모바일 앱 또는 웹에서 [`/output-style`](https://code.claude.com/docs/ko/output-styles#change-your-output-style)을 실행했거나, 세션으로 전달된 메시지에 해당 명령이 포함되어 있었습니다. 이러한 턴은 계정 소유자가 보낸 것이 아닐 수 있으므로, Claude Code는 해당 턴에서 [기본 제공 스타일](https://code.claude.com/docs/ko/output-styles.md#built-in-output-styles)만 나열하고 선택하며, 명령이 스타일을 나열하거나 입력한 이름을 인식하지 못할 때마다 이 안내를 추가합니다. [사용자 지정 스타일](https://code.claude.com/docs/ko/output-styles.md#create-a-custom-output-style) 이름은 존재하지 않는 이름과 동일한 응답을 받습니다.4177[Remote Control](https://code.claude.com/docs/ko/remote-control.md)을 통해 모바일 앱이나 웹에서 [`/output-style`](https://code.claude.com/docs/ko/output-styles#change-your-output-style)을 실행했거나, 세션으로 전달된 메시지에 해당 명령이 포함되어 있었습니다. 이러한 턴은 계정 소유자에게서 온 것이 아닐 수 있으므로, Claude Code는 해당 턴에서 [기본 제공 스타일](https://code.claude.com/docs/ko/output-styles.md#built-in-output-styles)만 나열하고 선택하며, 명령이 스타일을 나열하거나 입력한 이름을 인식하지 못할 때마다 이 안내를 추가합니다. [사용자 지정 스타일](https://code.claude.com/docs/ko/output-styles.md#create-a-custom-output-style) 이름에는 존재하지 않는 이름과 같은 응답이 표시됩니다:
4090 4178
4091```text theme={null}4179```text theme={null}
4092Custom output styles can't be selected over Remote Control or from a relayed message. Select one in the session itself, or pick a built-in style here.4180Custom output styles can't be selected over Remote Control or from a relayed message. Select one in the session itself, or pick a built-in style here.
4094 4182
4095**해결 방법:**4183**해결 방법:**
4096 4184
4097* 기본 제공 스타일을 선택합니다(예: `/output-style concise`)4185* 기본 제공 스타일을 선택합니다. 예: `/output-style concise`
4098* 사용자 지정 스타일을 사용하려면 프로젝트의 `.claude/settings.local.json`에서 [`outputStyle`](https://code.claude.com/docs/ko/settings-reference#outputstyle)을 설정하거나, 세션 자체의 터미널이 있다면 그곳에서 `/output-style <style>`을 실행합니다4186* 사용자 지정 스타일을 사용하려면 프로젝트의 `.claude/settings.local.json`에서 [`outputStyle`](https://code.claude.com/docs/ko/settings-reference#outputstyle)을 설정하거나, 세션 자체 터미널이 있는 경우 해당 터미널에서 `/output-style <style>`을 실행합니다
4099 4187
4100### 출력 스타일은 이 세션이 로드하지 않는 로컬 설정에 저장됨4188### Output styles are saved to local settings which this session doesn't load
4101 4189
4102설정 소스에서 `local`을 제외하는 세션에서 `/output-style <style>` 또는 `/config outputStyle=<style>`로 [출력 스타일](https://code.claude.com/docs/ko/output-styles.md)을 전환하려고 했습니다. 예를 들어 [`settingSources`](https://code.claude.com/docs/ko/agent-sdk/typescript#options)에서 `"local"`을 제외한 [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/typescript.md) 세션이나, `local`을 제외하는 [`--setting-sources`](https://code.claude.com/docs/ko/cli-reference#cli-flags) 값으로 시작된 CLI 세션이 있습니다. 두 명령 모두 스타일을 `.claude/settings.local.json`에 저장하는데, 이러한 세션은 이 파일을 다시 읽지 않으므로 Claude Code는 효과가 없을 설정을 쓰는 대신 거부합니다.4190설정 소스에서 `local`이 제외된 세션에서 `/output-style <style>` 또는 `/config outputStyle=<style>`로 [출력 스타일](https://code.claude.com/docs/ko/output-styles.md)을 전환하려고 했습니다. 예를 들어 [`settingSources`](https://code.claude.com/docs/ko/agent-sdk/typescript#options)에서 `"local"`이 빠진 [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/typescript.md) 세션이나, `local`이 빠진 [`--setting-sources`](https://code.claude.com/docs/ko/cli-reference#cli-flags) 값으로 시작한 CLI 세션이 있습니다. 두 명령 모두 스타일을 `.claude/settings.local.json`에 저장하는데, 이러한 세션은 이 파일을 다시 읽지 않으므로 Claude Code는 효과가 없을 설정을 쓰는 대신 거부합니다:
4103 4191
4104```text theme={null}4192```text theme={null}
4105Output styles are saved to local settings (.claude/settings.local.json), which this session doesn't load, so the style can't be changed here.4193Output styles are saved to local settings (.claude/settings.local.json), which this session doesn't load, so the style can't be changed here.
4108**해결 방법:**4196**해결 방법:**
4109 4197
4110* 세션의 설정 소스에 `local`을 추가하고 다시 전환합니다4198* 세션의 설정 소스에 `local`을 추가하고 다시 전환합니다
4111* 프로젝트의 `.claude/settings.json` 또는 `~/.claude/settings.json`처럼 세션이 로드하는 설정 파일에서 [`outputStyle`](https://code.claude.com/docs/ko/settings-reference#outputstyle) 키를 설정합니다. TypeScript SDK에서는 대신 인라인 `settings` 객체 내에서 `outputStyle`을 설정합니다. [출력 스타일 활성화](https://code.claude.com/docs/ko/agent-sdk/modifying-system-prompts.md#activate-an-output-style)를 참조하십시오4199* 프로젝트의 `.claude/settings.json`이나 `~/.claude/settings.json`처럼 세션이 로드하는 설정 파일에서 [`outputStyle`](https://code.claude.com/docs/ko/settings-reference#outputstyle) 키를 설정합니다. TypeScript SDK에서는 대신 인라인 `settings` 객체 안에서 `outputStyle`을 설정합니다. [출력 스타일 활성화](https://code.claude.com/docs/ko/agent-sdk/modifying-system-prompts.md#activate-an-output-style)를 참조하십시오
4112 4200
4113### /recap은 직접 요청할 때만 실행됨4201### /recap only runs when you ask for it yourself
4114 4202
4115[`/recap`](https://code.claude.com/docs/ko/interactive-mode#session-recap) 요청이 사용자 본인의 입력에서 온 것이 아닙니다. Slack, Teams 또는 [프로젝트](https://code.claude.com/docs/ko/claude-projects.md) 스레드에서 세션으로 전달된 메시지에 포함되어 도착했거나, [클라우드 예약 작업](https://code.claude.com/docs/ko/routines.md) 또는 다른 프로그램이 보낸 프롬프트에 포함되어 도착했습니다.4203[`/recap`](https://code.claude.com/docs/ko/interactive-mode#session-recap) 요청이 사용자 자신의 입력에서 온 것이 아닙니다. Slack, Teams 또는 [프로젝트](https://code.claude.com/docs/ko/claude-projects.md) 스레드에서 세션으로 전달된 메시지로 도착했거나, [클라우드 예약 작업](https://code.claude.com/docs/ko/routines.md)이나 다른 프로그램이 보낸 프롬프트로 도착했습니다.
4116 4204
4117전달된 메시지는 사용자가 직접 작성한 경우에도 이 안내를 받습니다. Claude Code는 전달되거나 자동화된 메시지가 세션을 실행하는 계정의 소유자로부터 온 것인지 알 수 없으므로, 요약 대신 다음 안내로 응답합니다.4205전달된 메시지는 사용자가 직접 작성한 경우에도 이 안내를 받습니다. Claude Code는 전달되거나 자동화된 메시지가 세션을 실행하는 계정의 소유자에게서 왔는지 판단할 수 없으므로, 요약 대신 이 안내로 응답합니다:
4118 4206
4119```text theme={null}4207```text theme={null}
4120/recap only runs when you ask for it yourself in this session: from the terminal, the Claude app or claude.ai/code, or over Remote Control. A message relayed from Slack, Teams or a project thread, or sent by a routine or another program, can't request it.4208/recap only runs when you ask for it yourself in this session: from the terminal, the Claude app or claude.ai/code, or over Remote Control. A message relayed from Slack, Teams or a project thread, or sent by a routine or another program, can't request it.
4121```4209```
4122 4210
4123`claude -p`에 전달하는 `/recap`이나, 사용자 자신의 [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/overview.md) 애플리케이션이 실행한 세션에 보내는 `/recap`은 사용자의 직접 입력으로 간주됩니다.4211`claude -p`에 전달하는 `/recap`이나, 자체 [Agent SDK](https://code.claude.com/docs/ko/agent-sdk/overview.md) 애플리케이션이 자신이 시작한 세션에 보내는 `/recap`은 사용자 자신의 입력으로 간주됩니다.
4124 4212
4125**해결 방법:**4213**해결 방법:**
4126 4214
4127* 세션을 직접 열고 그곳에서 `/recap`을 실행합니다: 해당 터미널, [Desktop 앱](https://code.claude.com/docs/ko/desktop.md) 또는 [모바일 앱](https://code.claude.com/docs/ko/mobile.md), [claude.ai/code](https://claude.ai/code), 또는 [Remote Control](https://code.claude.com/docs/ko/remote-control.md)을 통해 실행할 수 있습니다4215* 세션을 직접 열고 해당 세션의 터미널, [Desktop 앱](https://code.claude.com/docs/ko/desktop.md) 또는 [모바일 앱](https://code.claude.com/docs/ko/mobile.md), [claude.ai/code](https://claude.ai/code), 또는 [Remote Control](https://code.claude.com/docs/ko/remote-control.md)을 통해 `/recap`을 실행합니다
4128* 클라우드 예약 작업이나 다른 프로그램이 보낸 경우 해당 프롬프트에서 `/recap`을 제거합니다4216* 클라우드 예약 작업이나 다른 프로그램이 보낸 경우 해당 프롬프트에서 `/recap`을 제거합니다
4129 4217
4130### /feedback is disabled by your organization's policy4218### /feedback is disabled by your organization's policy
4131 4219
4132이 메시지는 조직의 정책이 Claude Code에서의 제품 피드백을 허용하지 않아 `/feedback`, `/bug`, `/share`가 피드백 대화 상자를 열지 않는다는 의미입니다. 메시지에는 Claude Code 프롬프트에 입력한 명령이 표시됩니다.4220이 메시지는 조직의 정책이 Claude Code에서의 제품 피드백을 허용하지 않으므로 `/feedback`, `/bug`, `/share`가 피드백 대화 상자를 열지 않는다는 의미입니다. 메시지에는 Claude Code 프롬프트에서 입력한 명령이 표시됩니다:
4133 4221
4134```text wrap theme={null}4222```text wrap theme={null}
4135/feedback is disabled by your organization's policy. To report a bug, open an issue at https://github.com/anthropics/claude-code/issues. Issues are public, so leave out anything confidential.4223/feedback is disabled by your organization's policy. To report a bug, open an issue at https://github.com/anthropics/claude-code/issues. Issues are public, so leave out anything confidential.
4136```4224```
4137 4225
4138메시지가 첫 문장만으로 표시될 수도 있습니다.4226메시지가 첫 번째 문장만으로 표시될 수도 있습니다.
4139 4227
4140**해결 방법:**4228**해결 방법:**
4141 4229
4142* 버그를 보고하려면 [github.com/anthropics/claude-code/issues](https://github.com/anthropics/claude-code/issues)에서 이슈를 엽니다. 이곳의 이슈는 누구나 읽을 수 있으므로 코드, 트랜스크립트 및 기타 기밀 정보는 포함하지 않습니다.4230* 버그를 보고하려면 [github.com/anthropics/claude-code/issues](https://github.com/anthropics/claude-code/issues)에서 이슈를 엽니다. 이곳의 이슈는 누구나 읽을 수 있으므로 코드, 트랜스크립트 및 기타 기밀 정보는 포함하지 마십시오.
4143 4231
4144v2.1.302 이전에는 전체 메시지가 `/feedback is disabled by your organization's policy. Contact your organization admin to enable it.`였습니다.4232v2.1.302 이전에는 전체 메시지가 `/feedback is disabled by your organization's policy. Contact your organization admin to enable it.`였습니다.
4145 4233
4666* **Claude가 작성한 명령의 경우**: 수정할 것이 없습니다. 메시지가 Claude에게 명령을 다시 작성하는 방법을 알려 줍니다.4754* **Claude가 작성한 명령의 경우**: 수정할 것이 없습니다. 메시지가 Claude에게 명령을 다시 작성하는 방법을 알려 줍니다.
4667* **스킬 또는 명령 파일의 경우**: 메시지는 `No shell command in <name> was run` 뒤에 표시됩니다. [문자를 찾아 제거하는 위치](#no-shell-command-was-run)를 참조하세요.4755* **스킬 또는 명령 파일의 경우**: 메시지는 `No shell command in <name> was run` 뒤에 표시됩니다. [문자를 찾아 제거하는 위치](#no-shell-command-was-run)를 참조하세요.
4668 4756
4757### Command approved before Claude Code restarted was not run
4758
4759사용자가 승인한 셸 명령이 실행되지 않았으며, Claude는 명령의 결과로 다음 메시지를 받습니다.
4760
4761```text wrap theme={null}
4762This call was not run. The command was approved before Claude Code restarted, and Claude Code could not confirm that the shell is back in the directory where it was approved. That directory may be gone or replaced, lie outside the directory where the session started, or be one that Claude Code needs approval to enter or is not allowed to examine. The shell's directory is <directory>. If the command still makes sense, cd to the directory it was meant for and make the call again; it may need approval again.
4763```
4764
4765메시지의 세 번째 문장은 대신 `It does not keep track of that directory across a restart in a session that has been in a worktree.`로 표시될 수 있습니다.
4766
4767**조치 방법:**
4768
4769* Claude가 계속 진행하도록 두고, 명령을 다시 승인하라는 요청을 받으면 프롬프트에 응답합니다.
4770
4669### File is too large to read as an image4771### File is too large to read as an image
4670 4772
4671Claude가 [Read 도구](https://code.claude.com/docs/ko/tools-reference.md#read-tool-behavior)로 파일을 이미지로 읽으려 했지만, 파일이 Read가 이미지 파일에서 불러올 수 있는 최대 크기인 128MB보다 큽니다. 아무것도 읽히지 않았으며, Claude는 도구 결과로 다음 오류를 받습니다.4773Claude가 [Read 도구](https://code.claude.com/docs/ko/tools-reference.md#read-tool-behavior)로 파일을 이미지로 읽으려 했지만, 파일이 Read가 이미지 파일에서 불러올 수 있는 최대 크기인 128MB보다 큽니다. 아무것도 읽히지 않았으며, Claude는 도구 결과로 다음 오류를 받습니다.
5818 5920
5819### 원격 관리형 설정을 로드하지 못함5921### 원격 관리형 설정을 로드하지 못함
5820 5922
5821세션이 [서버 관리형 설정](https://code.claude.com/docs/ko/server-managed-settings.md) 적용 대상이지만 Claude Code가 설정을 가져오지 못했거나 서버가 반환한 내용을 적용하지 못했으므로 대화형 세션에서 이 경고를 표시합니다.5923세션이 [서버 관리형 설정](https://code.claude.com/docs/ko/server-managed-settings.md) 적용 대상이지만 Claude Code가 설정을 가져오지 못했거나 서버가 반환한 내용을 적용하지 못했으므로 대화형 세션과 Claude Desktop의 Code 탭에서 이 경고를 표시합니다.
5822 5924
5823괄호 안의 원인은 `network error`, `request timed out`, `authentication rejected (401)`처럼 무엇이 실패했는지를 나타냅니다. `no setting in the server response could be applied as written` 원인은 서버가 응답했지만 반환된 설정 중 [검증](https://code.claude.com/docs/ko/server-managed-settings.md#invalid-entries-in-delivered-settings)을 통과한 것이 없음을 의미합니다. v2.1.282 이전에는 이 원인이 `server returned invalid settings`로 표시되었습니다.5925괄호 안의 원인은 `network error`, `request timed out`, `authentication rejected (401)`처럼 무엇이 실패했는지를 나타냅니다. `no setting in the server response could be applied as written` 원인은 서버가 응답했지만 반환된 설정 중 [검증](https://code.claude.com/docs/ko/server-managed-settings.md#invalid-entries-in-delivered-settings)을 통과한 것이 없음을 의미합니다. v2.1.282 이전에는 이 원인이 `server returned invalid settings`로 표시되었습니다.
5824 5926
5827* **이전에 성공한 가져오기에서 캐시된 설정**: Claude Code는 [보류된 환경 변수](https://code.claude.com/docs/ko/server-managed-settings.md#fetch-and-caching-behavior)를 제외한 캐시된 정책으로 세션을 실행하며, 줄에 `using cached policy`가 표시됩니다.5929* **이전에 성공한 가져오기에서 캐시된 설정**: Claude Code는 [보류된 환경 변수](https://code.claude.com/docs/ko/server-managed-settings.md#fetch-and-caching-behavior)를 제외한 캐시된 정책으로 세션을 실행하며, 줄에 `using cached policy`가 표시됩니다.
5828* **캐시 없음**: Claude Code는 서버 관리형 설정 없이 세션을 실행하며, 줄에 `no remote policy applied`가 표시됩니다.5930* **캐시 없음**: Claude Code는 서버 관리형 설정 없이 세션을 실행하며, 줄에 `no remote policy applied`가 표시됩니다.
5829 5931
5932Code 탭에서는 메시지를 보낼 때 경고가 대화에 한 줄로 나타나며, 가져오기 상태가 바뀌면 새 줄이 나타납니다. 관련된 세 가지 메시지도 같은 방식으로 나타납니다:
5933
5934* `Remote managed settings are still loading`: 세션이 진행될 때 가져오기가 아직 실행 중이었습니다
5935* `Remote managed settings did not load`: 가져오기가 응답 없이 끝났습니다
5936* `Remote managed settings have now loaded`: 이러한 경고 중 하나가 표시된 후 설정이 로드되었으며, 줄의 나머지 부분은 원격 정책이 적용되는지를 나타냅니다
5937
5830**할 일:**5938**할 일:**
5831 5939
5832* 메시지가 명시한 원인에 따라 조치하세요: 네트워크 원인의 경우 이 머신이 `api.anthropic.com`에 도달할 수 있는지 확인하고, 인증 원인의 경우 `/status`로 로그인 상태를 확인하세요.5940* 메시지가 명시한 원인에 따라 조치하세요: 네트워크 원인의 경우 이 머신이 `api.anthropic.com`에 도달할 수 있는지 확인하고, 인증 원인의 경우 `/status`로 로그인 상태를 확인하세요.
5835 5943
5836v2.1.248 이전에는 Claude Code가 설정 가져오기 실패를 디버그 로그에서만 보고했습니다.5944v2.1.248 이전에는 Claude Code가 설정 가져오기 실패를 디버그 로그에서만 보고했습니다.
5837 5945
5946### Claude Code가 조직의 설정을 로드하지 못함
5947
5948[서버 관리형 설정](https://code.claude.com/docs/ko/server-managed-settings.md)을 포함한 조직의 설정이 먼저 로드되어야 하는데 Claude Code가 이를 로드하지 못했으므로 세션이 시작되지 않았습니다. 예를 들면 다음과 같습니다:
5949
5950```text theme={null}
5951Claude Code couldn't reach Anthropic to load your organization's settings (could not connect). <Organization name> requires them before a session can start.
5952```
5953
5954메시지가 `Claude Code can't start this session yet` 제목의 대화 상자에 표시되면, 설정이 로드되는 즉시 대화 상자가 닫히고 세션이 시작됩니다.
5955
5956[비대화형 모드](https://code.claude.com/docs/ko/headless.md)와 [백그라운드 세션](https://code.claude.com/docs/ko/agent-view.md)에서는 Claude Code가 대신 메시지를 출력하고 상태 1로 종료합니다.
5957
5958**할 일:**
5959
5960* **`could not connect`, 또는 `the reply came from a network proxy, not Anthropic`**: 네트워크 연결을 확인하고, 회사 네트워크에서는 IT 부서에 `api.anthropic.com/api/claude_code/policy_limits` 및 `api.anthropic.com/api/claude_code/settings`로의 HTTPS를 허용하도록 요청하세요. 그런 다음 **Retry now**를 선택하거나 명령을 다시 실행하세요.
5961* **`timed out`, `Anthropic returned an error`, 또는 `Anthropic asked it to retry shortly`**: 대화 상자가 재시도하도록 두거나 나중에 명령을 다시 실행하세요. 계속 발생하면 [status.anthropic.com](https://status.anthropic.com)을 확인하세요.
5962* **`still loading`, 또는 `couldn't verify your sign-in with Anthropic yet`**: 대화 상자가 재시도하도록 두거나 명령을 다시 실행하세요. 로그인 메시지가 계속 다시 나타나면 셸에서 `claude auth login`을 실행하여 다시 로그인하세요.
5963* **`Your Claude session has expired`**: 이 머신에 저장된 로그인이 더 이상 유효하지 않으므로 재시도해도 도움이 되지 않습니다. 대화 상자에서 **Sign in again**을 선택하여 Claude Code를 닫은 다음, 셸에서 `claude auth login`을 실행하세요. 이 명령은 세션을 시작할 수 없는 동안에도 작동합니다.
5964* **`none of the settings the server returned could be applied as written`**: 관리자에게 조직의 [서버 관리형 설정](https://code.claude.com/docs/ko/server-managed-settings.md#invalid-entries-in-delivered-settings)을 수정하도록 요청한 다음 재시도하세요.
5965
5838### 관리형 설정이 승인되지 않음5966### 관리형 설정이 승인되지 않음
5839 5967
5840조직의 [서버 관리형 설정](https://code.claude.com/docs/ko/server-managed-settings.md)에 승인이 필요한 설정이 포함되어 있는데 [보안 승인 대화 상자](https://code.claude.com/docs/ko/server-managed-settings.md#security-approval-dialogs)를 거부했으므로, Claude Code는 설정을 적용하지 않고 종료합니다:5968조직의 [서버 관리형 설정](https://code.claude.com/docs/ko/server-managed-settings.md)에 승인이 필요한 설정이 포함되어 있는데 [보안 승인 대화 상자](https://code.claude.com/docs/ko/server-managed-settings.md#security-approval-dialogs)를 거부했으므로, Claude Code는 설정을 적용하지 않고 종료합니다:
6294 6422
6295v2.1.257 이전에는 `claude doctor`가 이러한 파일을 표시하지 않았으며, 이전 버전에서도 세션이 강제 종료되면 같은 자리 표시자가 남습니다.6423v2.1.257 이전에는 `claude doctor`가 이러한 파일을 표시하지 않았으며, 이전 버전에서도 세션이 강제 종료되면 같은 자리 표시자가 남습니다.
6296 6424
6425### 나중에 이 변경을 다시 수행하세요: \~/.claude.json을 업데이트할 수 없음
6426
6427stderr의 이 알림은 로그인이나 신뢰 프롬프트에 대한 응답처럼 [`~/.claude.json`](https://code.claude.com/docs/ko/claude-directory#ce-claude-json)에 대한 변경 사항이 파일에 저장되지 않았다는 의미입니다:
6428
6429```text theme={null}
6430Make this change again later: /home/user/.claude.json could not be updated, so it applies to this session only.
6431```
6432
6433**할 일:**
6434
6435* 이후 세션에서 변경을 다시 수행하세요. 예를 들어 `/login`을 다시 실행하거나 신뢰 프롬프트에 다시 응답하세요.
6436
6297## 응답 품질이 평소보다 낮아 보입니다6437## 응답 품질이 평소보다 낮아 보입니다
6298 6438
6299Claude의 답변이 예상보다 덜 능력 있어 보이지만 오류가 표시되지 않는 경우, 원인은 일반적으로 모델 자체가 아니라 대화 상태입니다. Claude Code는 모델 버전을 자동으로 변경하지 않습니다. 다음의 경우에 폴백 모델로 전환할 수 있습니다:6439Claude의 답변이 예상보다 덜 능력 있어 보이지만 오류가 표시되지 않는 경우, 원인은 일반적으로 모델 자체가 아니라 대화 상태입니다. Claude Code는 모델 버전을 자동으로 변경하지 않습니다. 다음의 경우에 폴백 모델로 전환할 수 있습니다:
