Skip to main content
Entri di halaman ini dikunci ke kesalahan yang Anda lihat. Masing-masing menyebutkan penyebab dan apa yang harus dilakukan.

​
CLI startup

​
CLINotFoundError: Claude Code not found

Python SDK meluncurkan Claude Code CLI sebagai subprocess. Ketika tidak dapat menemukan executable claude, koneksi gagal dengan CLINotFoundError:
Pesan mencakup jalur yang dikonfigurasi ketika Anda menetapkan ClaudeAgentOptions(cli_path=...) dan menunjuk ke file yang hilang. Tanpa cli_path, SDK mencari PATH Anda dan lokasi instalasi umum, dan pesan mencakup instruksi instalasi untuk platform Anda. Untuk memperbaikinya:
  • Instal Claude Code jika belum diinstal. Lihat Install Claude Code untuk perintah di platform Anda.
  • Jika Anda menetapkan cli_path, konfirmasi file ada dan merupakan executable claude.
  • Jika Anda mengandalkan resolusi PATH, konfirmasi claude --version berfungsi di lingkungan yang sama tempat aplikasi Anda berjalan. Proses yang Anda luncurkan di luar shell Anda, seperti dari IDE atau manajer layanan, sering kali berjalan dengan PATH yang berbeda.
TypeScript SDK mencari CLI di paket platform bundel-nya dan jalur yang Anda tetapkan di pathToClaudeCodeExecutable. Cocokkan pesan yang Anda lihat:
  • Native CLI binary for <platform>-<arch> not found: paket platform bundel hilang, paling sering karena instalasi melewatkan dependensi opsional. Instal ulang @anthropic-ai/claude-agent-sdk tanpa melewatkan dependensi opsional, atau arahkan pathToClaudeCodeExecutable ke instalasi native. Dalam executable file tunggal yang dibangun dengan bun build --compile, pesan yang sama memiliki penyebab dan solusi yang berbeda. Lihat Compile to a single executable.
  • Claude Code native binary not found at <path> atau Claude Code executable not found at <path>. Is options.pathToClaudeCodeExecutable set?: file di jalur yang diselesaikan hilang, atau proses tidak dapat mengaksesnya. Konfirmasi file ada di jalur itu dan bahwa proses dapat mengaksesnya.

​
CLIConnectionError: Refusing to execute batch script

Di Windows, koneksi gagal dengan CLIConnectionError ketika jalur CLI yang digunakan Python SDK adalah skrip batch .bat atau .cmd, termasuk shim claude.cmd yang dibuat instalasi npm:
Penolakan ini adalah pengerasan keamanan yang disengaja, bukan instalasi yang rusak. Windows menjalankan skrip batch dengan menulis ulang spawn menjadi invokasi cmd.exe /c, dan cmd.exe mem-parse ulang seluruh baris perintah pada waktu eksekusi, jadi nilai argumen dapat menjalankan perintah yang disuntikkan. Sebagian besar instalasi Windows tidak pernah mencapai kesalahan ini. Wheel Windows x64 dari claude-agent-sdk membundel claude.exe, dan SDK lebih memilih CLI bundel, kemudian executable claude.exe native apa pun yang dapat ditemukannya, sebelum kembali ke shim batch. Anda melihat penolakan dalam dua kasus:
  • Anda menetapkan ClaudeAgentOptions(cli_path=...) ke file .bat atau .cmd, seperti shim claude.cmd npm.
  • Instalasi Anda tidak memiliki claude.exe bundel atau native, misalnya instalasi sumber di ARM64 Windows di mana satu-satunya claude di PATH Anda adalah shim npm.
Untuk memperbaikinya, berikan SDK executable native alih-alih skrip batch:
  • Jika Anda menetapkan ClaudeAgentOptions(cli_path=...), arahkan ke claude.exe atau hapus opsi. SDK melewatkan penemuan saat cli_path diatur, jadi instalasi native saja tidak dapat berlaku.
  • Instal Claude Code secara native di PowerShell: irm https://claude.ai/install.ps1 | iex
  • Di Windows x64, instal wheel claude-agent-sdk, yang membundel claude.exe.
Sebelum claude-agent-sdk 0.2.124, Python SDK menjalankan skrip batch melalui cmd.exe tanpa pemeriksaan ini.

​
CLIConnectionError: Failed to start Claude Code

SDK menemukan file di jalur yang diselesaikan tetapi tidak dapat meluncurkannya. Python menaikkan kegagalan ini sebagai CLIConnectionError. TypeScript menolak iterasi pesan dengan kesalahan yang tidak membawa kelas SDK. Tabel di bawah memetakan setiap pesan ke apa yang diberitahukannya. Cocokkan pesan yang Anda lihat: Di kedua SDK, penyebab umum adalah jalur yang diselesaikan yang menunjuk ke sesuatu yang tidak dapat dijalankan, seperti file teks, direktori, atau file tanpa izin eksekusi. Baca saran libc pesan binary native sebagai salah satu kemungkinan penyebab. Untuk memperbaikinya di salah satu SDK:
  • Konfirmasi jalur yang dikonfigurasi menunjuk ke executable claude itu sendiri dan bahwa file memiliki izin eksekusi.
  • Jika Anda tidak memerlukan jalur kustom, hapus cli_path di Python atau pathToClaudeCodeExecutable di TypeScript sehingga SDK menemukan CLI sendiri, lebih memilih salinan bundel-nya.
  • Ketika binary yang gagal adalah salinan bundel SDK dalam image kontainer, instal ulang SDK selama build image sehingga binary bundel cocok dengan platform kontainer, atau bangun ulang image untuk arsitektur yang dijalankannya. Penyebab umum adalah binary yang tidak cocok dengan arsitektur atau libc kontainer, atau yang kehilangan izin eksekusi dalam build image.

​
CLIConnectionError: Not connected

Memanggil metode ClaudeSDKClient di Python sebelum klien terhubung, atau setelah terputus, menaikkan CLIConnectionError dengan pesan ini:
Lakukan apa yang dikatakan pesan. Baik panggil await client.connect() sebelum metode klien lainnya, atau buka klien dengan async with ClaudeSDKClient() as client:, yang terhubung saat masuk.

​
CLI process exit

Entri di bagian ini berarti proses Claude Code berakhir saat aplikasi Anda menggunakannya. Kesalahan mana yang Anda lihat tergantung pada bahasa SDK dan apakah CLI melaporkan hasil kesalahan sebelum keluar.

​
ProcessError: Command failed with exit code

Python SDK menaikkan ProcessError ketika proses Claude Code keluar dengan kode bukan nol:
Pesan menyatakan kode keluar dua kali, dan baris Error output adalah teks tetap daripada output kesalahan proses Anda. Teks tetap yang sama mengisi atribut stderr pengecualian. Atribut exit_code pengecualian membawa kode. Untuk menangkap apa yang benar-benar ditulis CLI ke stderr, berikan callback stderr di ClaudeAgentOptions dan catat apa yang diterimanya. ProcessError telanjang berarti CLI keluar tanpa melaporkan hasil kesalahan. Ketika CLI melaporkan satu, SDK menaikkan ResultError sebagai gantinya, tercakup dalam Claude Code returned an error result. ResultError subkelas ProcessError, jadi except ProcessError menangkap keduanya. Untuk menanganinya secara berbeda, letakkan klausa except ResultError terlebih dahulu. Sebelum claude-agent-sdk 0.2.140, Python SDK menaikkan keluar hasil kesalahan sebagai Exception biasa daripada ResultError.

​
Claude Code process exited with code N

Pembungkus IDE juga mencetak pesan ini, dan referensi kesalahan mencakupnya untuk VS Code dan peluncur lainnya. Entri ini mencakup apa yang diterima kode TypeScript SDK Anda. SDK menampilkan keluar CLI bukan nol sebagai Error biasa yang menolak loop for await atas pesan query(). Tidak ada kelas kesalahan SDK untuk ditangkap, jadi bungkus loop dalam try/catch dan cocokkan pada pesan:
Ketika CLI menulis ke stderr, pesan berakhir dengan ekor itu. Untuk menangkap aliran penuh, berikan callback stderr dalam opsi query. Proses yang dibunuh oleh sinyal melaporkan Claude Code process terminated by signal <name> dalam bentuk yang sama.

​
Claude Code returned an error result

Kedua SDK mengganti kesalahan keluar proses dengan pesan ini ketika CLI melaporkan hasil kesalahan sebelum keluar:
Teks setelah titik dua adalah laporan CLI tentang apa yang salah, jadi mulai dari sana daripada dengan keluar itu sendiri. Python menaikkan ini sebagai ResultError, yang atribut data-nya membawa hasil kesalahan penuh. TypeScript menolak loop pesan dengan Error biasa yang membawa bentuk pesan yang sama.

​
Structured outputs

​
structured_output is None but the result says success

Pesan hasil dapat berakhir dengan subtype: "success" sementara structured_output adalah None di Python atau undefined di TypeScript. Jalankan selesai, tetapi tidak ada output yang divalidasi. Salah satu cara untuk mencapai ini adalah skema yang tidak dapat dipenuhi output apa pun, misalnya batasan panjang yang bertentangan. Jalankan berakhir tanpa kesalahan validasi, dan satu-satunya sinyal adalah structured_output yang hilang. Perlakukan hasil ini sebagai kegagalan dalam kode aplikasi. Periksa baik bahwa subtype adalah success dan bahwa structured_output ada sebelum menggunakannya. Bagian Error handling menunjukkan pola ini untuk kedua SDK. Jika terjadi berulang kali dengan skema yang Anda percaya benar, verifikasi skema dapat dipenuhi, kemudian sederhanakan sampai output divalidasi, dan perkenalkan kembali batasan satu per satu.

​
Report a new issue

Jika kesalahan Anda tidak tercakup di sini, periksa masalah terbuka atau ajukan yang baru di repositori SDK: claude-agent-sdk-typescript atau claude-agent-sdk-python. Sertakan teks kesalahan penuh dan versi SDK Anda.