Skip to main content
Les entrées de cette page sont indexées selon l’erreur que vous voyez. Chacune indique la cause et ce qu’il faut faire.

​
Démarrage du CLI

​
CLINotFoundError : Claude Code introuvable

Le SDK Python lance le CLI Claude Code en tant que sous-processus. Quand il ne peut pas trouver un exécutable claude, la connexion échoue avec une CLINotFoundError :
Le message inclut le chemin configuré quand vous définissez ClaudeAgentOptions(cli_path=...) et qu’il pointe vers un fichier manquant. Sans cli_path, le SDK recherche dans votre PATH et les emplacements d’installation courants, et le message inclut les instructions d’installation pour votre plateforme. Pour corriger cela :
  • Installez Claude Code s’il n’est pas installé. Consultez Installer Claude Code pour la commande sur votre plateforme.
  • Si vous avez défini cli_path, confirmez que le fichier existe et qu’il s’agit de l’exécutable claude.
  • Si vous comptez sur la résolution PATH, confirmez que claude --version fonctionne dans le même environnement que celui dans lequel votre application s’exécute. Les processus que vous lancez en dehors de votre shell, par exemple à partir d’un IDE ou d’un gestionnaire de services, s’exécutent souvent avec un PATH différent.
Le SDK TypeScript recherche le CLI dans son paquet de plateforme fourni et le chemin que vous avez défini dans pathToClaudeCodeExecutable. Faites correspondre le message que vous voyez :
  • Native CLI binary for <platform>-<arch> not found : le paquet de plateforme fourni est manquant, le plus souvent parce que l’installation a ignoré les dépendances optionnelles. Réinstallez @anthropic-ai/claude-agent-sdk sans ignorer les dépendances optionnelles, ou pointez pathToClaudeCodeExecutable vers une installation native. Dans un exécutable monofichier construit avec bun build --compile, le même message a une cause et une correction différentes. Consultez Compiler en un seul exécutable.
  • Claude Code native binary not found at <path> ou Claude Code executable not found at <path>. Is options.pathToClaudeCodeExecutable set? : le fichier au chemin résolu est manquant, ou le processus ne peut pas y accéder. Confirmez que le fichier existe à ce chemin et que le processus peut y accéder.

​
CLIConnectionError : Refus d’exécuter un script batch

Sur Windows, la connexion échoue avec une CLIConnectionError quand le chemin du CLI que le SDK Python utilise est un script batch .bat ou .cmd, y compris le shim claude.cmd qu’une installation npm crée :
Le refus est un durcissement de sécurité délibéré, pas une installation cassée. Windows exécute les scripts batch en réécrivant le spawn en une invocation cmd.exe /c, et cmd.exe réanalyse toute la ligne de commande au moment de l’exécution, donc une valeur d’argument peut exécuter des commandes injectées. La plupart des installations Windows ne rencontrent jamais cette erreur. La wheel Windows x64 de claude-agent-sdk inclut un claude.exe, et le SDK préfère le CLI fourni, puis tout claude.exe natif qu’il peut découvrir, avant de revenir à un shim batch. Vous voyez le refus dans deux cas :
  • Vous avez défini ClaudeAgentOptions(cli_path=...) vers un fichier .bat ou .cmd, comme le shim claude.cmd de npm.
  • Votre installation n’a pas de claude.exe fourni ou natif, par exemple une installation source sur ARM64 Windows où le seul claude sur votre PATH est le shim npm.
Pour corriger cela, donnez au SDK un exécutable natif au lieu d’un script batch :
  • Si vous avez défini ClaudeAgentOptions(cli_path=...), pointez-le vers un claude.exe ou supprimez l’option. Le SDK ignore la découverte tant que cli_path est défini, donc une installation native seule ne peut pas prendre effet.
  • Installez Claude Code nativement dans PowerShell : irm https://claude.ai/install.ps1 | iex
  • Sur Windows x64, installez la wheel claude-agent-sdk, qui inclut claude.exe.
Avant claude-agent-sdk 0.2.124, le SDK Python lançait les scripts batch via cmd.exe sans cette vérification.

​
CLIConnectionError : Impossible de démarrer Claude Code

Le SDK a trouvé un fichier au chemin résolu mais n’a pas pu le lancer. Python lève ces défaillances en tant que CLIConnectionError. TypeScript rejette l’itération de message avec une erreur ne portant aucune classe SDK. Le tableau ci-dessous mappe chaque message à ce qu’il vous dit. Faites correspondre le message que vous voyez : Dans les deux SDK, la cause habituelle est un chemin résolu qui pointe vers quelque chose qui ne peut pas s’exécuter, comme un fichier texte, un répertoire ou un fichier sans permission d’exécution. Lisez la suggestion libc du message binaire natif comme une cause possible. Pour corriger cela dans l’un ou l’autre SDK :
  • Confirmez que le chemin configuré pointe vers l’exécutable claude lui-même et que le fichier a la permission d’exécution.
  • Si vous n’avez pas besoin d’un chemin personnalisé, supprimez cli_path en Python ou pathToClaudeCodeExecutable en TypeScript pour que le SDK trouve un CLI par lui-même, en préférant sa copie fournie.
  • Quand le binaire défaillant est la copie fournie du SDK dans une image conteneur, réinstallez le SDK pendant la construction de l’image pour que le binaire fourni corresponde à la plateforme du conteneur, ou reconstruisez l’image pour l’architecture sur laquelle elle s’exécute. La cause habituelle est un binaire qui ne correspond pas à l’architecture ou à la libc du conteneur, ou un qui a perdu sa permission d’exécution dans la construction de l’image.

​
CLIConnectionError : Non connecté

Appeler une méthode ClaudeSDKClient en Python avant que le client se soit connecté, ou après qu’il se soit déconnecté, lève une CLIConnectionError avec ce message :
Faites ce que le message dit. Appelez soit await client.connect() avant toute autre méthode client, soit ouvrez le client avec async with ClaudeSDKClient() as client:, qui se connecte à l’entrée.

​
Sortie du processus CLI

Les entrées de cette section signifient que le processus Claude Code s’est terminé pendant que votre application l’utilisait. L’erreur que vous voyez dépend du langage SDK et du fait que le CLI ait signalé un résultat d’erreur avant sa sortie.

​
ProcessError : Commande échouée avec le code de sortie

Le SDK Python lève une ProcessError quand le processus Claude Code se termine avec un code non nul :
Le message indique le code de sortie deux fois, et la ligne Error output est du texte fixe plutôt que la sortie d’erreur de votre processus. Le même texte fixe remplit l’attribut stderr de l’exception. L’attribut exit_code de l’exception porte le code. Pour capturer ce que le CLI a réellement écrit sur stderr, passez un callback stderr dans ClaudeAgentOptions et enregistrez ce qu’il reçoit. Une ProcessError nue signifie que le CLI s’est terminé sans signaler un résultat d’erreur. Quand le CLI en a signalé un, le SDK lève ResultError à la place, couvert dans Claude Code a retourné un résultat d’erreur. ResultError est une sous-classe de ProcessError, donc except ProcessError capture les deux. Pour les gérer différemment, mettez la clause except ResultError en premier. Avant claude-agent-sdk 0.2.140, le SDK Python levait les sorties de résultat d’erreur en tant qu’une Exception simple plutôt qu’une ResultError.

​
Le processus Claude Code s’est terminé avec le code N

Les wrappers IDE impriment aussi ce message, et la référence d’erreur la couvre pour VS Code et d’autres lanceurs. Cette entrée couvre ce que votre code SDK TypeScript reçoit. Le SDK surface une sortie CLI non nulle en tant qu’une Error simple qui rejette la boucle for await sur les messages de query(). Il n’y a pas de classe d’erreur SDK à capturer, donc enveloppez la boucle dans try/catch et faites correspondre le message :
Quand le CLI a écrit sur stderr, le message se termine par la fin de celui-ci. Pour capturer le flux complet, passez un callback stderr dans les options de requête. Un processus tué par un signal signale Claude Code process terminated by signal <name> de la même forme.

​
Claude Code a retourné un résultat d’erreur

Les deux SDK remplacent l’erreur de sortie du processus par ce message quand le CLI a signalé un résultat d’erreur avant de se terminer :
Le texte après les deux points est le rapport du CLI sur ce qui s’est mal passé, donc commencez par là plutôt que par la sortie elle-même. Python lève cela en tant qu’une ResultError, dont l’attribut data porte le résultat d’erreur complet. TypeScript rejette la boucle de message avec une Error simple portant la même forme de message.

​
Sorties structurées

​
structured_output est None mais le résultat dit succès

Un message de résultat peut se terminer par subtype: "success" tandis que structured_output est None en Python ou undefined en TypeScript. L’exécution se termine, mais aucune sortie validée n’existe. Une façon de rencontrer cela est un schéma qu’aucune sortie ne peut satisfaire, par exemple des contraintes de longueur conflictuelles. L’exécution se termine sans erreur de validation, et le seul signal est le structured_output manquant. Traitez ce résultat comme un échec dans le code d’application. Vérifiez à la fois que subtype est success et que structured_output est présent avant de l’utiliser. La section Gestion des erreurs montre ce modèle pour les deux SDK. Si cela se produit à plusieurs reprises avec un schéma que vous croyez correct, vérifiez que le schéma est satisfaisable, puis simplifiez-le jusqu’à ce que les sorties se valident, et réintroduisez les contraintes une à la fois.

​
Signaler un nouveau problème

Si votre erreur n’est pas couverte ici, vérifiez les problèmes ouverts ou déposez-en un nouveau dans les référentiels SDK : claude-agent-sdk-typescript ou claude-agent-sdk-python. Incluez le texte d’erreur complet et votre version SDK.