Skip to main content
Die Einträge auf dieser Seite sind nach dem Fehler, den Sie sehen, sortiert. Jeder Eintrag nennt die Ursache und was zu tun ist.

​
CLI-Start

​
CLINotFoundError: Claude Code nicht gefunden

Das Python SDK startet die Claude Code CLI als Unterprozess. Wenn es keine claude-Ausführungsdatei finden kann, schlägt die Verbindung mit einem CLINotFoundError fehl:
Die Meldung enthält den konfigurierten Pfad, wenn Sie ClaudeAgentOptions(cli_path=...) setzen und dieser auf eine fehlende Datei verweist. Ohne cli_path durchsucht das SDK Ihren PATH und häufige Installationsorte, und die Meldung enthält Installationsanweisungen für Ihre Plattform. So beheben Sie das Problem:
  • Installieren Sie Claude Code, falls es nicht installiert ist. Siehe Claude Code installieren für den Befehl auf Ihrer Plattform.
  • Wenn Sie cli_path setzen, bestätigen Sie, dass die Datei existiert und die claude-Ausführungsdatei ist.
  • Wenn Sie sich auf PATH-Auflösung verlassen, bestätigen Sie, dass claude --version in der gleichen Umgebung funktioniert, in der Ihre Anwendung läuft. Prozesse, die Sie außerhalb Ihrer Shell starten, z. B. von einer IDE oder einem Service Manager, laufen oft mit einem anderen PATH.
Das TypeScript SDK sucht die CLI in seinem gebündelten Plattformpaket und dem Pfad, den Sie in pathToClaudeCodeExecutable setzen. Passen Sie die Meldung an, die Sie sehen:
  • Native CLI binary for <platform>-<arch> not found: Das gebündelte Plattformpaket fehlt, meistens weil die Installation optionale Abhängigkeiten übersprungen hat. Installieren Sie @anthropic-ai/claude-agent-sdk neu, ohne optionale Abhängigkeiten zu überspringen, oder verweisen Sie pathToClaudeCodeExecutable auf eine native Installation. In einer einzelnen ausführbaren Datei, die mit bun build --compile erstellt wurde, hat die gleiche Meldung eine andere Ursache und Lösung. Siehe In eine einzelne ausführbare Datei kompilieren.
  • Claude Code native binary not found at <path> oder Claude Code executable not found at <path>. Is options.pathToClaudeCodeExecutable set?: Die Datei im aufgelösten Pfad fehlt, oder der Prozess kann nicht darauf zugreifen. Bestätigen Sie, dass die Datei in diesem Pfad existiert und dass der Prozess darauf zugreifen kann.

​
CLIConnectionError: Refusing to execute batch script

Unter Windows schlägt die Verbindung mit einem CLIConnectionError fehl, wenn der CLI-Pfad, den das Python SDK verwendet, ein .bat- oder .cmd-Batch-Skript ist, einschließlich des claude.cmd-Shims, das eine npm-Installation erstellt:
Die Weigerung ist absichtliche Sicherheitshärtung, nicht eine fehlerhafte Installation. Windows führt Batch-Skripte aus, indem es den Spawn in einen cmd.exe /c-Aufruf umschreibt, und cmd.exe analysiert die gesamte Befehlszeile zur Ausführungszeit neu, sodass ein Argumentwert injizierte Befehle ausführen kann. Die meisten Windows-Installationen erreichen diesen Fehler nie. Das Windows x64-Wheel von claude-agent-sdk enthält eine claude.exe, und das SDK bevorzugt die gebündelte CLI, dann jede native claude.exe, die es entdecken kann, bevor es auf einen Batch-Shim zurückfällt. Sie sehen die Weigerung in zwei Fällen:
  • Sie setzen ClaudeAgentOptions(cli_path=...) auf eine .bat- oder .cmd-Datei, z. B. das claude.cmd-Shim von npm.
  • Ihre Installation hat keine gebündelte oder native claude.exe, z. B. eine Quellinstallation auf ARM64 Windows, wo die einzige claude auf Ihrem PATH das npm-Shim ist.
Um das Problem zu beheben, geben Sie dem SDK eine native ausführbare Datei statt eines Batch-Skripts:
  • Wenn Sie ClaudeAgentOptions(cli_path=...) setzen, verweisen Sie auf eine claude.exe oder entfernen Sie die Option. Das SDK überspringt die Erkennung, während cli_path gesetzt ist, sodass eine native Installation allein nicht wirksam werden kann.
  • Installieren Sie Claude Code nativ in PowerShell: irm https://claude.ai/install.ps1 | iex
  • Auf x64 Windows installieren Sie das claude-agent-sdk-Wheel, das claude.exe enthält.
Vor claude-agent-sdk 0.2.124 spawnten das Python SDK Batch-Skripte über cmd.exe ohne diese Überprüfung.

​
CLIConnectionError: Failed to start Claude Code

Das SDK hat eine Datei im aufgelösten Pfad gefunden, konnte sie aber nicht starten. Python löst diese Fehler als CLIConnectionError aus. TypeScript lehnt die Nachrichteniteration mit einem Fehler ab, der keine SDK-Klasse trägt. Die folgende Tabelle ordnet jede Meldung dem zu, was sie Ihnen sagt. Passen Sie die Meldung an, die Sie sehen: In beiden SDKs ist die übliche Ursache ein aufgelöster Pfad, der auf etwas verweist, das nicht ausgeführt werden kann, z. B. eine Textdatei, ein Verzeichnis oder eine Datei ohne Ausführungsberechtigung. Lesen Sie den libc-Vorschlag der Meldung der nativen Binärdatei als eine mögliche Ursache. Um das Problem in beiden SDKs zu beheben:
  • Bestätigen Sie, dass der konfigurierte Pfad auf die claude-Ausführungsdatei selbst verweist und dass die Datei Ausführungsberechtigung hat.
  • Wenn Sie keinen benutzerdefinierten Pfad benötigen, entfernen Sie cli_path in Python oder pathToClaudeCodeExecutable in TypeScript, damit das SDK eine CLI selbst findet und seine gebündelte Kopie bevorzugt.
  • Wenn die fehlerhafte Binärdatei die gebündelte Kopie des SDK in einem Container-Image ist, installieren Sie das SDK während des Image-Builds neu, damit die gebündelte Binärdatei der Plattform des Containers entspricht, oder erstellen Sie das Image für die Architektur, auf der es läuft, neu. Die übliche Ursache ist eine Binärdatei, die nicht der Architektur oder libc des Containers entspricht, oder eine, die während des Image-Builds ihre Ausführungsberechtigung verloren hat.

​
CLIConnectionError: Not connected

Das Aufrufen einer ClaudeSDKClient-Methode in Python, bevor der Client verbunden ist, oder nachdem er getrennt wurde, löst einen CLIConnectionError mit dieser Meldung aus:
Tun Sie, was die Meldung sagt. Rufen Sie entweder await client.connect() vor jeder anderen Client-Methode auf, oder öffnen Sie den Client mit async with ClaudeSDKClient() as client:, was beim Eintritt verbindet.

​
CLI-Prozessbeendigung

Die Einträge in diesem Abschnitt bedeuten, dass der Claude Code-Prozess beendet wurde, während Ihre Anwendung ihn verwendete. Welcher Fehler Sie sehen, hängt von der SDK-Sprache und davon ab, ob die CLI ein Fehlerergebnis gemeldet hat, bevor sie beendet wurde.

​
ProcessError: Command failed with exit code

Das Python SDK löst einen ProcessError aus, wenn der Claude Code-Prozess mit einem Nicht-Null-Code beendet wird:
Die Meldung gibt den Exit-Code zweimal an, und die Error output-Zeile ist fester Text statt der Fehlerausgabe Ihres Prozesses. Der gleiche feste Text füllt das stderr-Attribut der Ausnahme. Das exit_code-Attribut der Ausnahme trägt den Code. Um zu erfassen, was die CLI tatsächlich in stderr geschrieben hat, übergeben Sie einen stderr-Callback in ClaudeAgentOptions und protokollieren Sie, was er empfängt. Ein bloßer ProcessError bedeutet, dass die CLI beendet wurde, ohne ein Fehlerergebnis zu melden. Wenn die CLI eines gemeldet hat, löst das SDK stattdessen ResultError aus, das in Claude Code hat ein Fehlerergebnis zurückgegeben behandelt wird. ResultError ist eine Unterklasse von ProcessError, sodass except ProcessError beide erfasst. Um sie unterschiedlich zu behandeln, setzen Sie die except ResultError-Klausel zuerst. Vor claude-agent-sdk 0.2.140 löste das Python SDK Fehler-Ergebnis-Exits als einfache Exception statt als ResultError aus.

​
Claude Code process exited with code N

IDE-Wrapper drucken diese Meldung auch, und die Fehlerreferenz behandelt sie für VS Code und andere Launcher. Dieser Eintrag behandelt, was Ihr TypeScript SDK-Code empfängt. Das SDK zeigt einen Nicht-Null-CLI-Exit als einfachen Error an, der die for await-Schleife über die Nachrichten von query() ablehnt. Es gibt keine SDK-Fehlerklasse zum Erfassen, daher wickeln Sie die Schleife in try/catch ein und passen Sie die Meldung an:
Wenn die CLI in stderr geschrieben hat, endet die Meldung mit dem Ende davon. Um den vollständigen Stream zu erfassen, übergeben Sie einen stderr-Callback in den Abfrageoptionen. Ein Prozess, der durch ein Signal beendet wurde, meldet Claude Code process terminated by signal <name> in der gleichen Form.

​
Claude Code returned an error result

Beide SDKs ersetzen den Prozessbeendigungsfehler durch diese Meldung, wenn die CLI ein Fehlerergebnis gemeldet hat, bevor sie beendet wurde:
Der Text nach dem Doppelpunkt ist der Bericht der CLI über das, was schief gelaufen ist, daher beginnen Sie dort statt mit dem Exit selbst. Python löst dies als ResultError aus, dessen data-Attribut das vollständige Fehlerergebnis trägt. TypeScript lehnt die Nachrichtenschleife mit einem einfachen Error ab, der die gleiche Nachrichtenform trägt.

​
Strukturierte Ausgaben

​
structured_output ist None, aber das Ergebnis sagt Erfolg

Eine Ergebnismeldung kann mit subtype: "success" enden, während structured_output in Python None oder in TypeScript undefined ist. Der Lauf wird abgeschlossen, aber es existiert keine validierte Ausgabe. Eine Möglichkeit, dies zu erreichen, ist ein Schema, das keine Ausgabe erfüllen kann, z. B. widersprüchliche Längenbeschränkungen. Der Lauf endet ohne Validierungsfehler, und das einzige Signal ist die fehlende structured_output. Behandeln Sie dieses Ergebnis als Fehler im Anwendungscode. Überprüfen Sie sowohl, dass subtype success ist, als auch dass structured_output vorhanden ist, bevor Sie es verwenden. Der Abschnitt Fehlerbehandlung zeigt dieses Muster für beide SDKs. Wenn es wiederholt mit einem Schema auftritt, das Sie für korrekt halten, überprüfen Sie, dass das Schema erfüllbar ist, vereinfachen Sie es dann, bis Ausgaben validieren, und führen Sie Beschränkungen nacheinander wieder ein.

​
Ein neues Problem melden

Wenn Ihr Fehler hier nicht behandelt wird, überprüfen Sie die offenen Probleme oder melden Sie ein neues in den SDK-Repositories: claude-agent-sdk-typescript oder claude-agent-sdk-python. Fügen Sie den vollständigen Fehlertext und Ihre SDK-Version ein.