Skip to main content
이 페이지의 항목들은 표시되는 오류를 기준으로 정렬되어 있습니다. 각 항목은 원인과 해결 방법을 설명합니다.

​
CLI 시작

​
CLINotFoundError: Claude Code not found

Python SDK는 Claude Code CLI를 서브프로세스로 실행합니다. claude 실행 파일을 찾을 수 없으면 연결이 CLINotFoundError로 실패합니다:
메시지에는 ClaudeAgentOptions(cli_path=...)를 설정했을 때 구성된 경로가 포함되며, 누락된 파일을 가리킵니다. cli_path가 없으면 SDK는 PATH와 일반적인 설치 위치를 검색하고, 메시지에는 플랫폼에 대한 설치 지침이 포함됩니다. 해결 방법:
  • Claude Code가 설치되지 않았으면 설치합니다. 플랫폼의 명령어는 Claude Code 설치를 참조하세요.
  • cli_path를 설정했으면 파일이 존재하고 claude 실행 파일인지 확인합니다.
  • PATH 해석에 의존하면 애플리케이션이 실행되는 동일한 환경에서 claude --version이 작동하는지 확인합니다. IDE나 서비스 관리자에서 실행하는 프로세스와 같이 셸 외부에서 실행하는 프로세스는 종종 다른 PATH로 실행됩니다.
TypeScript SDK는 번들된 플랫폼 패키지와 pathToClaudeCodeExecutable에 설정한 경로에서 CLI를 찾습니다. 표시되는 메시지와 일치시킵니다:
  • Native CLI binary for <platform>-<arch> not found: 번들된 플랫폼 패키지가 누락되었으며, 대부분 설치 시 선택적 종속성을 건너뛰었기 때문입니다. 선택적 종속성을 건너뛰지 않고 @anthropic-ai/claude-agent-sdk를 다시 설치하거나, pathToClaudeCodeExecutable을 네이티브 설치로 지정합니다. bun build --compile로 빌드한 단일 파일 실행 파일에서는 동일한 메시지가 다른 원인과 해결 방법을 가집니다. 단일 실행 파일로 컴파일을 참조하세요.
  • 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로 실패합니다:
거부는 의도적인 보안 강화이며, 손상된 설치가 아닙니다. Windows는 배치 스크립트를 cmd.exe /c 호출로 다시 작성하여 실행하고, cmd.exe는 실행 시 전체 명령줄을 다시 구문 분석하므로 인수 값이 주입된 명령을 실행할 수 있습니다. 대부분의 Windows 설치는 이 오류에 도달하지 않습니다. Windows x64 claude-agent-sdk 휠은 claude.exe를 번들로 포함하고, SDK는 번들된 CLI를 선호한 다음 발견할 수 있는 모든 네이티브 claude.exe를 선호하고, 배치 shim으로 폴백하기 전에 선호합니다. 두 가지 경우에 거부가 표시됩니다:
  • ClaudeAgentOptions(cli_path=...)를 npm의 claude.cmd shim과 같은 .bat 또는 .cmd 파일로 설정했습니다.
  • 설치에 번들된 또는 네이티브 claude.exe가 없습니다. 예를 들어 PATH의 유일한 claude가 npm shim인 ARM64 Windows의 소스 설치입니다.
해결 방법은 배치 스크립트 대신 네이티브 실행 파일을 SDK에 제공하는 것입니다:
  • ClaudeAgentOptions(cli_path=...)를 설정했으면 claude.exe로 지정하거나 옵션을 제거합니다. SDK는 cli_path가 설정된 동안 검색을 건너뛰므로 네이티브 설치만으로는 효과가 없습니다.
  • PowerShell에서 Claude Code를 네이티브로 설치합니다: irm https://claude.ai/install.ps1 | iex
  • x64 Windows에서 claude.exe를 번들로 포함하는 claude-agent-sdk 휠을 설치합니다.
claude-agent-sdk 0.2.124 이전에는 Python SDK가 이 확인 없이 cmd.exe를 통해 배치 스크립트를 생성했습니다.

​
CLIConnectionError: Failed to start Claude Code

SDK는 해석된 경로에서 파일을 찾았지만 실행할 수 없었습니다. Python은 이러한 실패를 CLIConnectionError로 발생시킵니다. TypeScript는 SDK 클래스가 없는 오류로 메시지 반복을 거부합니다. 아래 표는 각 메시지를 그것이 알려주는 것으로 매핑합니다. 표시되는 메시지와 일치시킵니다: 두 SDK 모두에서 일반적인 원인은 텍스트 파일, 디렉토리 또는 실행 권한이 없는 파일과 같이 실행할 수 없는 것을 가리키는 해석된 경로입니다. 네이티브 바이너리 메시지의 libc 제안을 가능한 원인 중 하나로 읽습니다. 두 SDK 모두에서 해결하려면:
  • 구성된 경로가 claude 실행 파일 자체를 가리키고 파일에 실행 권한이 있는지 확인합니다.
  • 사용자 정의 경로가 필요하지 않으면 Python에서 cli_path를 제거하거나 TypeScript에서 pathToClaudeCodeExecutable을 제거하여 SDK가 자체적으로 CLI를 찾도록 하고, 번들된 복사본을 선호합니다.
  • 실패한 바이너리가 컨테이너 이미지의 SDK 번들 복사본일 때 이미지 빌드 중에 SDK를 다시 설치하여 번들된 바이너리가 컨테이너의 플랫폼과 일치하도록 하거나, 실행되는 아키텍처에 대해 이미지를 다시 빌드합니다. 일반적인 원인은 컨테이너의 아키텍처 또는 libc와 일치하지 않는 바이너리이거나 이미지 빌드에서 실행 권한을 잃은 바이너리입니다.

​
CLIConnectionError: Not connected

Python에서 클라이언트가 연결되기 전에 또는 연결이 끊긴 후에 ClaudeSDKClient 메서드를 호출하면 다음 메시지와 함께 CLIConnectionError가 발생합니다:
메시지가 말하는 대로 하세요. 다른 클라이언트 메서드 전에 await client.connect()를 호출하거나 async with ClaudeSDKClient() as client:로 클라이언트를 열어서 진입 시 연결합니다.

​
CLI 프로세스 종료

이 섹션의 항목들은 애플리케이션이 사용 중일 때 Claude Code 프로세스가 종료되었음을 의미합니다. 표시되는 오류는 SDK 언어와 CLI가 종료 전에 오류 결과를 보고했는지 여부에 따라 달라집니다.

​
ProcessError: Command failed with exit code

Python SDK는 Claude Code 프로세스가 0이 아닌 코드로 종료될 때 ProcessError를 발생시킵니다:
메시지는 종료 코드를 두 번 나타내고, Error output 줄은 프로세스의 실제 오류 출력이 아닌 고정 텍스트입니다. 동일한 고정 텍스트가 예외의 stderr 속성을 채웁니다. 예외의 exit_code 속성은 코드를 전달합니다. CLI가 실제로 stderr에 작성한 내용을 캡처하려면 ClaudeAgentOptions에서 stderr 콜백을 전달하고 수신한 내용을 기록합니다. 단순한 ProcessError는 CLI가 오류 결과를 보고하지 않고 종료되었음을 의미합니다. CLI가 보고했을 때 SDK는 대신 ResultError를 발생시키며, Claude Code returned an error result에서 다룹니다. ResultError는 ProcessError를 서브클래싱하므로 except ProcessError는 둘 다 캐치합니다. 다르게 처리하려면 except ResultError 절을 먼저 배치합니다. claude-agent-sdk 0.2.140 이전에는 Python SDK가 오류 결과 종료를 ResultError 대신 일반 Exception으로 발생시켰습니다.

​
Claude Code process exited with code N

IDE 래퍼도 이 메시지를 인쇄하고, 오류 참조는 VS Code 및 기타 런처에 대해 다룹니다. 이 항목은 TypeScript SDK 코드가 수신하는 것을 다룹니다. SDK는 0이 아닌 CLI 종료를 query()의 메시지에 대한 for await 루프를 거부하는 일반 Error로 표시합니다. 캐치할 SDK 오류 클래스가 없으므로 루프를 try/catch로 래핑하고 메시지와 일치시킵니다:
CLI가 stderr에 작성했을 때 메시지는 그 끝으로 끝납니다. 전체 스트림을 캡처하려면 쿼리 옵션에서 stderr 콜백을 전달합니다. 신호로 종료된 프로세스는 동일한 형식으로 Claude Code process terminated by signal <name>을 보고합니다.

​
Claude Code returned an error result

두 SDK 모두 CLI가 종료 전에 오류 결과를 보고했을 때 프로세스 종료 오류를 이 메시지로 바꿉니다:
콜론 뒤의 텍스트는 무엇이 잘못되었는지에 대한 CLI의 보고이므로 종료 자체보다는 여기서 시작합니다. Python은 이를 ResultError로 발생시키며, 그 data 속성은 전체 오류 결과를 전달합니다. TypeScript는 동일한 메시지 형태를 전달하는 일반 Error로 메시지 루프를 거부합니다.

​
구조화된 출력

​
structured_output is None but the result says success

결과 메시지는 subtype: "success"로 끝날 수 있지만 Python에서 structured_output은 None이거나 TypeScript에서 undefined입니다. 실행이 완료되지만 검증된 출력이 없습니다. 이를 발생시키는 한 가지 방법은 충돌하는 길이 제약과 같이 출력이 만족할 수 없는 스키마입니다. 실행은 검증 오류 없이 끝나고 유일한 신호는 누락된 structured_output입니다. 애플리케이션 코드에서 이 결과를 실패로 취급합니다. structured_output을 사용하기 전에 subtype이 success이고 structured_output이 존재하는지 확인합니다. 오류 처리 섹션은 두 SDK 모두에 대해 이 패턴을 보여줍니다. 올바르다고 생각하는 스키마에서 반복적으로 발생하면 스키마가 만족 가능한지 확인한 다음 출력이 검증될 때까지 단순화하고 제약을 한 번에 하나씩 다시 도입합니다.

​
새 문제 보고

오류가 여기에 포함되지 않으면 SDK 저장소에서 열린 문제를 확인하거나 새 문제를 제출합니다: claude-agent-sdk-typescript 또는 claude-agent-sdk-python. 전체 오류 텍스트와 SDK 버전을 포함합니다.