Skip to main content
Las entradas en esta página están codificadas según el error que ve. Cada una nombra la causa y qué hacer.

​
Inicio de CLI

​
CLINotFoundError: Claude Code no encontrado

El SDK de Python inicia la CLI de Claude Code como un subproceso. Cuando no puede encontrar un ejecutable claude, la conexión falla con un CLINotFoundError:
El mensaje incluye la ruta configurada cuando establece ClaudeAgentOptions(cli_path=...) y apunta a un archivo faltante. Sin cli_path, el SDK busca en su PATH y ubicaciones de instalación comunes, e incluye instrucciones de instalación para su plataforma. Para corregirlo:
  • Instale Claude Code si no está instalado. Consulte Install Claude Code para el comando en su plataforma.
  • Si establece cli_path, confirme que el archivo existe y es el ejecutable claude.
  • Si confía en la resolución de PATH, confirme que claude --version funciona en el mismo entorno en el que se ejecuta su aplicación. Los procesos que inicia fuera de su shell, como desde un IDE o un administrador de servicios, a menudo se ejecutan con un PATH diferente.
El SDK de TypeScript busca la CLI en su paquete de plataforma incluido y la ruta que establece en pathToClaudeCodeExecutable. Haga coincidir el mensaje que ve:
  • Native CLI binary for <platform>-<arch> not found: el paquete de plataforma incluido falta, la mayoría de las veces porque la instalación omitió dependencias opcionales. Reinstale @anthropic-ai/claude-agent-sdk sin omitir dependencias opcionales, o apunte pathToClaudeCodeExecutable a una instalación nativa. En un ejecutable de archivo único compilado con bun build --compile, el mismo mensaje tiene una causa y solución diferentes. Consulte Compile to a single executable.
  • Claude Code native binary not found at <path> o Claude Code executable not found at <path>. Is options.pathToClaudeCodeExecutable set?: el archivo en la ruta resuelta falta, o el proceso no puede acceder a él. Confirme que el archivo existe en esa ruta y que el proceso puede acceder a él.

​
CLIConnectionError: Refusing to execute batch script

En Windows, la conexión falla con un CLIConnectionError cuando la ruta de CLI que usa el SDK de Python es un script por lotes .bat o .cmd, incluido el shim claude.cmd que crea una instalación npm:
La negativa es un endurecimiento de seguridad deliberado, no una instalación rota. Windows ejecuta scripts por lotes reescribiendo el spawn en una invocación cmd.exe /c, y cmd.exe reanaliza toda la línea de comandos en tiempo de ejecución, por lo que un valor de argumento puede ejecutar comandos inyectados. La mayoría de las instalaciones de Windows nunca alcanzan este error. La rueda x64 de Windows de claude-agent-sdk incluye un claude.exe, y el SDK prefiere la CLI incluida, luego cualquier claude.exe nativo que pueda descubrir, antes de recurrir a un shim por lotes. Ve la negativa en dos casos:
  • Establece ClaudeAgentOptions(cli_path=...) en un archivo .bat o .cmd, como el shim claude.cmd de npm.
  • Su instalación no tiene un claude.exe incluido o nativo, por ejemplo una instalación de fuente en ARM64 Windows donde el único claude en su PATH es el shim npm.
Para corregirlo, proporcione al SDK un ejecutable nativo en lugar de un script por lotes:
  • Si establece ClaudeAgentOptions(cli_path=...), apúntelo a un claude.exe o elimine la opción. El SDK omite el descubrimiento mientras cli_path está establecido, por lo que una instalación nativa sola no puede tener efecto.
  • Instale Claude Code de forma nativa en PowerShell: irm https://claude.ai/install.ps1 | iex
  • En Windows x64, instale la rueda claude-agent-sdk, que incluye claude.exe.
Antes de claude-agent-sdk 0.2.124, el SDK de Python generaba scripts por lotes a través de cmd.exe sin esta verificación.

​
CLIConnectionError: Failed to start Claude Code

El SDK encontró un archivo en la ruta resuelta pero no pudo iniciarlo. Python genera estos errores como un CLIConnectionError. TypeScript rechaza la iteración del mensaje con un error sin clase SDK. La tabla a continuación asigna cada mensaje a lo que le dice. Haga coincidir el mensaje que ve: En ambos SDK, la causa habitual es una ruta resuelta que apunta a algo que no puede ejecutarse, como un archivo de texto, un directorio o un archivo sin permiso de ejecución. Lea la sugerencia de libc del mensaje de binario nativo como una posible causa. Para corregirlo en cualquier SDK:
  • Confirme que la ruta configurada apunta al ejecutable claude en sí y que el archivo tiene permiso de ejecución.
  • Si no necesita una ruta personalizada, elimine cli_path en Python o pathToClaudeCodeExecutable en TypeScript para que el SDK encuentre una CLI por su cuenta, prefiriendo su copia incluida.
  • Cuando el binario que falla es la copia incluida del SDK en una imagen de contenedor, reinstale el SDK durante la compilación de la imagen para que el binario incluido coincida con la plataforma del contenedor, o reconstruya la imagen para la arquitectura en la que se ejecuta. La causa habitual es un binario que no coincide con la arquitectura o libc del contenedor, o uno que perdió su permiso de ejecución en la compilación de la imagen.

​
CLIConnectionError: Not connected

Llamar a un método ClaudeSDKClient en Python antes de que el cliente se haya conectado, o después de que se haya desconectado, genera un CLIConnectionError con este mensaje:
Haga lo que dice el mensaje. Llame a await client.connect() antes de cualquier otro método de cliente, o abra el cliente con async with ClaudeSDKClient() as client:, que se conecta al entrar.

​
Salida del proceso CLI

Las entradas en esta sección significan que el proceso de Claude Code terminó mientras su aplicación lo estaba usando. Qué error ve depende del idioma del SDK y de si la CLI reportó un resultado de error antes de salir.

​
ProcessError: Command failed with exit code

El SDK de Python genera un ProcessError cuando el proceso de Claude Code sale con un código distinto de cero:
El mensaje indica el código de salida dos veces, y la línea Error output es texto fijo en lugar de la salida de error de su proceso. El mismo texto fijo llena el atributo stderr de la excepción. El atributo exit_code de la excepción lleva el código. Para capturar lo que la CLI realmente escribió en stderr, pase un callback stderr en ClaudeAgentOptions y registre lo que recibe. Un ProcessError simple significa que la CLI salió sin reportar un resultado de error. Cuando la CLI reportó uno, el SDK genera ResultError en su lugar, cubierto en Claude Code returned an error result. ResultError subclasifica ProcessError, por lo que except ProcessError captura ambos. Para manejarlos de manera diferente, coloque la cláusula except ResultError primero. Antes de claude-agent-sdk 0.2.140, el SDK de Python generaba salidas de resultado de error como una Exception simple en lugar de un ResultError.

​
Claude Code process exited with code N

Los wrappers de IDE también imprimen este mensaje, y la referencia de error la cubre para VS Code y otros lanzadores. Esta entrada cubre lo que recibe su código del SDK de TypeScript. El SDK presenta una salida de CLI con código distinto de cero como un Error simple que rechaza el bucle for await sobre los mensajes de query(). No hay clase de error SDK para capturar, así que envuelva el bucle en try/catch y haga coincidir el mensaje:
Cuando la CLI escribió en stderr, el mensaje termina con la cola de la misma. Para capturar la secuencia completa, pase un callback stderr en las opciones de consulta. Un proceso eliminado por una señal reporta Claude Code process terminated by signal <name> en la misma forma.

​
Claude Code returned an error result

Ambos SDK reemplazan el error de salida del proceso con este mensaje cuando la CLI reportó un resultado de error antes de salir:
El texto después de los dos puntos es el informe de la CLI sobre qué salió mal, así que comience allí en lugar de con la salida en sí. Python genera esto como un ResultError, cuyo atributo data lleva el resultado de error completo. TypeScript rechaza el bucle de mensajes con un Error simple que lleva la misma forma de mensaje.

​
Salidas estructuradas

​
structured_output es None pero el resultado dice éxito

Un mensaje de resultado puede terminar con subtype: "success" mientras structured_output es None en Python o undefined en TypeScript. La ejecución se completa, pero no existe una salida validada. Una forma de alcanzar esto es un esquema que ninguna salida puede satisfacer, por ejemplo restricciones de longitud conflictivas. La ejecución termina sin un error de validación, y la única señal es el structured_output faltante. Trate este resultado como un error en el código de la aplicación. Verifique tanto que subtype sea success como que structured_output esté presente antes de usarlo. La sección Error handling muestra este patrón para ambos SDK. Si sucede repetidamente con un esquema que cree que es correcto, verifique que el esquema sea satisfacible, luego simplifíquelo hasta que las salidas se validen, e reintroduzca las restricciones una a la vez.

​
Reportar un nuevo problema

Si su error no está cubierto aquí, verifique los problemas abiertos o presente uno nuevo en los repositorios del SDK: claude-agent-sdk-typescript o claude-agent-sdk-python. Incluya el texto de error completo y su versión del SDK.