Agent SDK 문제 해결 (Troubleshoot the Agent SDK)

기준일: 2026-10-23
공식 기준: Troubleshoot the Agent SDK

개요

이 페이지는 Agent SDK의 CLI 시작, CLI 프로세스 종료, 구조화 출력 오류를 화면에 보이는 오류 메시지 기준으로 정리합니다. 항목마다 원인과 조치를 적습니다. hook이 실행되지 않거나 skill이 쓰이지 않는 것처럼 특정 기능에 묶인 증상은 그 기능 페이지의 문제 해결 절을 봅니다.

핵심 개념

증상	볼 곳
skill을 못 찾음, skill이 안 쓰임, Invalid skill name	Skills의 Troubleshooting
MCP 서버 failed 상태, 툴이 호출되지 않음, SDK MCP 서버의 툴 누락, 연결 타임아웃, 툴 출력이 최대 토큰 초과	MCP의 Troubleshooting
플러그인이 로드되지 않음, 플러그인 skill이 안 보임	Plugins의 Troubleshooting
서브에이전트에 위임하지 않음, 파일 시스템 기반 agent 미로드	Subagents의 Troubleshooting
checkpointing 옵션 미인식, UUID 없는 user 메시지, No file checkpoint found, File rewinding is not enabled, ProcessTransport is not ready for writing	File checkpointing의 Troubleshooting
hook 미실행, matcher 필터링 이상, hook 타임아웃, 예상 밖 툴 차단, 수정한 입력 미반영, Python에서 session hook 없음, 서브에이전트 권한 프롬프트 증식, 서브에이전트와 재귀 hook 루프, systemMessage가 출력에 안 보임	Hooks의 Fix common issues
내 머신에서는 되는데 배포한 서비스·컨테이너에서 실패	Hosting의 Troubleshoot deployment failures
Not logged in, Invalid API key, API Error, 429, There's an issue with the selected model	오류 레퍼런스
CLINotFoundError, CLIConnectionError, ProcessError, Claude Code process exited with code N, Claude Code returned an error result, structured_output이 None	이 페이지

상세

CLI 시작

CLINotFoundError: Claude Code not found

Python SDK는 Claude Code CLI를 하위 프로세스로 띄웁니다. claude 실행 파일을 못 찾으면 연결이 CLINotFoundError로 실패합니다.

Claude Code not found at: /your/configured/path

ClaudeAgentOptions(cli_path=...)가 없는 파일을 가리키면 메시지에 그 경로가 들어갑니다. cli_path가 없으면 SDK가 PATH와 흔한 설치 위치를 찾고, 메시지에 플랫폼별 설치 안내가 붙습니다.

• Claude Code가 없으면 설치합니다.
• cli_path를 지정했다면 파일이 존재하고 claude 실행 파일인지 확인합니다.
• PATH에 기대고 있다면 애플리케이션이 실제로 도는 환경에서 claude --version이 되는지 확인합니다. IDE나 서비스 매니저처럼 셸 밖에서 띄운 프로세스는 PATH가 다른 경우가 많습니다.

TypeScript SDK는 번들된 플랫폼 패키지와 pathToClaudeCodeExecutable 경로에서 CLI를 찾습니다.

메시지	원인과 조치
Native CLI binary for <platform>-<arch> not found	번들 플랫폼 패키지가 없음. 대개 optional dependency를 건너뛴 설치가 원인이므로 optional dependency를 포함해 @anthropic-ai/claude-agent-sdk를 다시 설치하거나, pathToClaudeCodeExecutable을 네이티브 설치로 지정. bun build --compile로 만든 단일 실행 파일에서는 원인과 해결이 다르므로 TypeScript 레퍼런스의 Compile to a single executable 참고
Claude Code native binary not found at <path> / Claude Code executable not found at <path>. Is options.pathToClaudeCodeExecutable set?	해석된 경로에 파일이 없거나 프로세스가 접근할 수 없음. 파일 존재와 접근 권한 확인

CLIConnectionError: Refusing to execute batch script

Windows에서 Python SDK가 쓰는 CLI 경로가 .bat·.cmd 배치 스크립트(npm 설치가 만드는 claude.cmd shim 포함)면 CLIConnectionError로 연결이 실패합니다.

Refusing to execute batch script 'C:\\Users\\you\\AppData\\Roaming\\npm\\claude.cmd': Windows runs .bat/.cmd files via cmd.exe, which can execute commands injected through CLI arguments, and no reliable escaping for cmd.exe exists. Use a native claude executable instead: install Claude Code natively (irm https://claude.ai/install.ps1 | iex), point ClaudeAgentOptions(cli_path=...) at a claude.exe, or install the claude-agent-sdk wheel for a platform that bundles claude.exe (e.g. Windows x64).

설치가 깨진 것이 아니라 의도한 보안 강화입니다. Windows는 배치 스크립트를 cmd.exe /c 호출로 바꿔 실행하고, cmd.exe가 실행 시점에 명령줄 전체를 다시 파싱하므로 인자 값으로 주입된 명령이 실행될 수 있습니다.

대부분의 Windows 설치는 이 오류를 만나지 않습니다. Windows x64용 claude-agent-sdk wheel이 claude.exe를 번들하고, SDK가 번들 CLI → 찾을 수 있는 네이티브 claude.exe → 배치 shim 순으로 고르기 때문입니다. 이 오류는 두 경우에 나옵니다.

• ClaudeAgentOptions(cli_path=...)를 npm의 claude.cmd 같은 .bat·.cmd 파일로 지정한 경우
• 번들·네이티브 claude.exe가 없는 경우(예: ARM64 Windows의 소스 설치에서 PATH의 claude가 npm shim뿐)

해결은 배치 스크립트 대신 네이티브 실행 파일을 주는 것입니다.

• cli_path를 지정했다면 claude.exe로 바꾸거나 옵션을 지웁니다. cli_path가 있으면 SDK가 탐색을 건너뛰므로 네이티브 설치만으로는 반영되지 않습니다.
• PowerShell에서 네이티브 설치: irm https://claude.ai/install.ps1 | iex
• x64 Windows에서는 claude.exe를 번들한 claude-agent-sdk wheel을 설치합니다.

claude-agent-sdk 0.2.124 이전의 Python SDK는 이 확인 없이 배치 스크립트를 cmd.exe로 실행했습니다.

CLIConnectionError: Failed to start Claude Code

해석된 경로에 파일은 있지만 실행하지 못한 경우입니다. Python은 CLIConnectionError로, TypeScript는 SDK 클래스 없는 오류로 메시지 반복을 reject합니다.

메시지	SDK	의미
Failed to start Claude Code: <detail>	Python	뒷부분은 운영체제의 오류
Claude Code executable at <path> exists but failed to launch	TypeScript	지정한 경로의 스크립트를 실행할 수 없음
Claude Code native binary at <path> exists but failed to launch	TypeScript	바이너리를 실행할 수 없음. libc 관련 제안이 붙음
Failed to spawn Claude Code process: <detail>	TypeScript	그 밖의 실행 실패

두 SDK 모두 보통 원인은 텍스트 파일, 디렉터리, 실행 권한 없는 파일처럼 실행할 수 없는 것을 가리키는 경로입니다. 네이티브 바이너리 메시지의 libc 제안은 가능한 원인 중 하나로 읽으세요.

• 지정 경로가 claude 실행 파일 자체이고 실행 권한이 있는지 확인합니다.
• 사용자 지정 경로가 필요 없으면 Python cli_path / TypeScript pathToClaudeCodeExecutable을 지워 SDK가 번들 사본을 우선으로 스스로 찾게 합니다.
• 컨테이너 이미지에서 SDK 번들 바이너리가 실패한다면, 이미지 빌드 중 SDK를 다시 설치해 컨테이너 플랫폼에 맞추거나 실제 실행 아키텍처용으로 이미지를 다시 빌드합니다. 아키텍처·libc 불일치나 이미지 빌드 중 실행 권한 손실이 흔한 원인입니다.

CLIConnectionError: Not connected

Python에서 연결 전이나 연결 해제 후 ClaudeSDKClient 메서드를 부르면 발생합니다.

Not connected. Call connect() first.

다른 메서드 전에 await client.connect()를 부르거나, 진입 시 연결하는 async with ClaudeSDKClient() as client:로 엽니다.

CLI 프로세스 종료

애플리케이션이 쓰는 도중 Claude Code 프로세스가 끝난 경우입니다. SDK 언어와, CLI가 종료 전에 error result를 보고했는지에 따라 오류가 다릅니다.

ProcessError: Command failed with exit code

Python SDK는 Claude Code 프로세스가 0이 아닌 코드로 끝나면 ProcessError를 던집니다.

Command failed with exit code 1 (exit code: 1)
Error output: Check stderr output for details

• 종료 코드가 두 번 나오고, Error output 줄은 실제 stderr가 아니라 고정 문구입니다. 예외의 stderr 속성도 같은 고정 문구이고, exit_code 속성에 코드가 들어 있습니다.
• CLI가 실제로 stderr에 쓴 내용을 보려면 ClaudeAgentOptions에 stderr 콜백을 넘겨 기록합니다.
• 맨 ProcessError는 CLI가 error result 없이 종료했다는 뜻입니다. error result를 보고했다면 SDK는 대신 ResultError를 던집니다. ResultError는 ProcessError의 하위 클래스라 except ProcessError가 둘 다 잡으므로, 따로 처리하려면 except ResultError를 먼저 둡니다.
• claude-agent-sdk 0.2.140 이전에는 error result 종료를 ResultError가 아닌 일반 Exception으로 던졌습니다.

Claude Code process exited with code N

IDE 래퍼도 이 메시지를 출력하며, VS Code 등 런처 관점은 오류 레퍼런스에 있습니다. TypeScript SDK에서는 0이 아닌 CLI 종료가 query() 메시지에 대한 for await 루프를 reject하는 일반 Error로 나옵니다. 잡을 SDK 오류 클래스가 없으므로 루프를 try/catch로 감싸 메시지로 구분합니다.

Claude Code process exited with code 1. stderr: <tail of the CLI's stderr>

CLI가 stderr에 쓴 내용이 있으면 메시지 끝에 그 꼬리가 붙습니다. 전체 스트림은 query options의 stderr 콜백으로 받습니다. 시그널로 종료되면 같은 형식으로 Claude Code process terminated by signal <name>이 나옵니다.

Claude Code returned an error result

CLI가 종료 전에 error result를 보고했으면 두 SDK 모두 프로세스 종료 오류 대신 이 메시지를 냅니다.

Claude Code returned an error result: <the CLI's own error report>

콜론 뒤가 CLI가 보고한 실제 원인이므로 종료 자체보다 그 내용부터 봅니다. Python은 data 속성에 전체 error result를 담은 ResultError로, TypeScript는 같은 메시지 형태의 일반 Error로 메시지 루프를 reject합니다.

구조화 출력

structured_output이 None인데 result는 success

result 메시지가 subtype: "success"로 끝났는데 structured_output이 Python에서 None, TypeScript에서 undefined일 수 있습니다. 실행은 끝났지만 검증된 출력은 없습니다.

애플리케이션 코드에서는 이 result를 실패로 다루세요. subtype이 success이고 structured_output이 있는지 둘 다 확인한 뒤 씁니다(패턴은 Structured outputs의 Error handling). 그다음 원인을 확인합니다.

• Claude가 거절한 요청: result 메시지의 stop_reason이 "refusal"인지 확인합니다. 다음 조치는 오류 레퍼런스의 Usage Policy refusal을 봅니다.
• 어떤 출력도 만족할 수 없는 스키마: 예를 들어 minLength가 maxLength보다 큰 문자열. 맞다고 생각하는 스키마에서 계속 structured_output이 빠지면 서로 모순되는 제약을 찾고, 없으면 출력이 검증될 때까지 스키마를 단순화한 뒤 제약을 하나씩 다시 넣습니다.

새 이슈 보고

여기 없는 오류라면 SDK 저장소의 열린 이슈를 확인하거나 새로 등록합니다: claude-agent-sdk-typescript, claude-agent-sdk-python. 전체 오류 텍스트와 SDK 버전을 함께 적으세요.

체크리스트

• 애플리케이션이 실제로 도는 환경에서 claude --version이 동작한다.
• TypeScript SDK를 optional dependency를 빼지 않고 설치했다.
• Windows에서 cli_path가 .cmd·.bat가 아닌 claude.exe를 가리킨다(또는 지정하지 않았다).
• 컨테이너 이미지의 SDK 번들 바이너리가 실행 아키텍처·libc와 맞는다.
• stderr 콜백으로 CLI의 실제 stderr를 기록한다.
• Python에서 except ResultError를 except ProcessError보다 먼저 둔다.
• 구조화 출력은 subtype과 structured_output을 둘 다 확인한 뒤 쓴다.

다음 단계

• Configure your agent에서 env·cwd 등 세션 구성을 점검합니다. Python의 cli_path는 Python 레퍼런스의 ClaudeAgentOptions를 봅니다.
• 배포 환경 문제는 Hosting, 인증·API 오류는 오류 레퍼런스를 봅니다.
• Python 레퍼런스·TypeScript 레퍼런스에서 예외 타입을 확인합니다.

기준일

이 문서는 2026-10-23에 공식 Troubleshoot the Agent SDK 페이지를 기준으로 작성했습니다. 오류 문구는 SDK 버전에 따라 바뀔 수 있으니 공식 원문을 함께 확인하세요.