Skip to main content
As entradas nesta página são organizadas de acordo com o erro que você vê. Cada uma nomeia a causa e o que fazer.

​
Inicialização do CLI

​
CLINotFoundError: Claude Code not found

O SDK Python inicia o CLI Claude Code como um subprocesso. Quando não consegue encontrar um executável claude, a conexão falha com um CLINotFoundError:
A mensagem inclui o caminho configurado quando você define ClaudeAgentOptions(cli_path=...) e ele aponta para um arquivo ausente. Sem cli_path, o SDK pesquisa seu PATH e locais de instalação comuns, e a mensagem inclui instruções de instalação para sua plataforma. Para corrigir:
  • Instale Claude Code se não estiver instalado. Consulte Install Claude Code para o comando em sua plataforma.
  • Se você definir cli_path, confirme que o arquivo existe e é o executável claude.
  • Se você depender da resolução de PATH, confirme que claude --version funciona no mesmo ambiente em que seu aplicativo é executado. Processos que você inicia fora do seu shell, como de um IDE ou gerenciador de serviços, geralmente são executados com um PATH diferente.
O SDK TypeScript procura o CLI em seu pacote de plataforma agrupado e no caminho que você define em pathToClaudeCodeExecutable. Corresponda à mensagem que você vê:
  • Native CLI binary for <platform>-<arch> not found: o pacote de plataforma agrupado está ausente, na maioria das vezes porque a instalação pulou dependências opcionais. Reinstale @anthropic-ai/claude-agent-sdk sem pular dependências opcionais, ou aponte pathToClaudeCodeExecutable para uma instalação nativa. Em um executável de arquivo único construído com bun build --compile, a mesma mensagem tem uma causa e correção diferentes. Consulte Compile to a single executable.
  • Claude Code native binary not found at <path> ou Claude Code executable not found at <path>. Is options.pathToClaudeCodeExecutable set?: o arquivo no caminho resolvido está ausente, ou o processo não consegue acessá-lo. Confirme que o arquivo existe nesse caminho e que o processo pode acessá-lo.

​
CLIConnectionError: Refusing to execute batch script

No Windows, a conexão falha com um CLIConnectionError quando o caminho do CLI que o SDK Python usa é um script em lote .bat ou .cmd, incluindo o shim claude.cmd que uma instalação npm cria:
A recusa é um endurecimento de segurança deliberado, não uma instalação quebrada. O Windows executa scripts em lote reescrevendo o spawn em uma invocação cmd.exe /c, e cmd.exe reanálisa toda a linha de comando no tempo de execução, portanto um valor de argumento pode executar comandos injetados. A maioria das instalações do Windows nunca atinge esse erro. A wheel x64 do Windows de claude-agent-sdk agrupa um claude.exe, e o SDK prefere o CLI agrupado, depois qualquer claude.exe nativo que possa descobrir, antes de recorrer a um shim em lote. Você vê a recusa em dois casos:
  • Você define ClaudeAgentOptions(cli_path=...) para um arquivo .bat ou .cmd, como o shim claude.cmd do npm.
  • Sua instalação não tem um claude.exe agrupado ou nativo, por exemplo uma instalação de origem no ARM64 Windows onde o único claude em seu PATH é o shim npm.
Para corrigir, dê ao SDK um executável nativo em vez de um script em lote:
  • Se você definir ClaudeAgentOptions(cli_path=...), aponte-o para um claude.exe ou remova a opção. O SDK pula a descoberta enquanto cli_path está definido, portanto uma instalação nativa sozinha não pode ter efeito.
  • Instale Claude Code nativamente no PowerShell: irm https://claude.ai/install.ps1 | iex
  • No Windows x64, instale a wheel claude-agent-sdk, que agrupa claude.exe.
Antes de claude-agent-sdk 0.2.124, o SDK Python gerava scripts em lote através de cmd.exe sem essa verificação.

​
CLIConnectionError: Failed to start Claude Code

O SDK encontrou um arquivo no caminho resolvido, mas não conseguiu iniciá-lo. Python gera essas falhas como um CLIConnectionError. TypeScript rejeita a iteração de mensagem com um erro sem classe SDK. A tabela abaixo mapeia cada mensagem para o que ela diz a você. Corresponda à mensagem que você vê: Em ambos os SDKs, a causa usual é um caminho resolvido que aponta para algo que não pode ser executado, como um arquivo de texto, um diretório ou um arquivo sem permissão de execução. Leia a sugestão de libc da mensagem de binário nativo como uma possível causa. Para corrigir em qualquer SDK:
  • Confirme que o caminho configurado aponta para o próprio executável claude e que o arquivo tem permissão de execução.
  • Se você não precisar de um caminho personalizado, remova cli_path em Python ou pathToClaudeCodeExecutable em TypeScript para que o SDK encontre um CLI por conta própria, preferindo sua cópia agrupada.
  • Quando o binário que falha é a cópia agrupada do SDK em uma imagem de contêiner, reinstale o SDK durante a construção da imagem para que o binário agrupado corresponda à plataforma do contêiner, ou reconstrua a imagem para a arquitetura em que é executada. A causa usual é um binário que não corresponde à arquitetura ou libc do contêiner, ou um que perdeu sua permissão de execução na construção da imagem.

​
CLIConnectionError: Not connected

Chamar um método ClaudeSDKClient em Python antes do cliente ter se conectado, ou depois de ter se desconectado, gera um CLIConnectionError com esta mensagem:
Faça o que a mensagem diz. Chame await client.connect() antes de qualquer outro método do cliente, ou abra o cliente com async with ClaudeSDKClient() as client:, que se conecta na entrada.

​
Saída do processo CLI

As entradas nesta seção significam que o processo Claude Code terminou enquanto seu aplicativo o estava usando. Qual erro você vê depende da linguagem do SDK e se o CLI relatou um resultado de erro antes de sair.

​
ProcessError: Command failed with exit code

O SDK Python gera um ProcessError quando o processo Claude Code sai com um código diferente de zero:
A mensagem declara o código de saída duas vezes, e a linha Error output é texto fixo em vez da saída de erro do seu processo. O mesmo texto fixo preenche o atributo stderr da exceção. O atributo exit_code da exceção carrega o código. Para capturar o que o CLI realmente escreveu em stderr, passe um callback stderr em ClaudeAgentOptions e registre o que ele recebe. Um ProcessError simples significa que o CLI saiu sem relatar um resultado de erro. Quando o CLI relatou um, o SDK gera ResultError em vez disso, coberto em Claude Code returned an error result. ResultError é uma subclasse de ProcessError, portanto except ProcessError captura ambos. Para tratá-los de forma diferente, coloque a cláusula except ResultError primeiro. Antes de claude-agent-sdk 0.2.140, o SDK Python gerava saídas de resultado de erro como uma Exception simples em vez de um ResultError.

​
Claude Code process exited with code N

Wrappers IDE também imprimem esta mensagem, e a referência de erro a cobre para VS Code e outros inicializadores. Esta entrada cobre o que seu código SDK TypeScript recebe. O SDK apresenta uma saída CLI com código diferente de zero como um Error simples que rejeita o loop for await sobre as mensagens de query(). Não há classe de erro SDK para capturar, portanto envolva o loop em try/catch e corresponda à mensagem:
Quando o CLI escreveu em stderr, a mensagem termina com a cauda dele. Para capturar o fluxo completo, passe um callback stderr nas opções de consulta. Um processo morto por um sinal relata Claude Code process terminated by signal <name> na mesma forma.

​
Claude Code returned an error result

Ambos os SDKs substituem o erro de saída do processo por esta mensagem quando o CLI relatou um resultado de erro antes de sair:
O texto após os dois pontos é o relatório do CLI sobre o que deu errado, portanto comece por lá em vez de com a saída em si. Python gera isso como um ResultError, cujo atributo data carrega o resultado de erro completo. TypeScript rejeita o loop de mensagem com um Error simples carregando a mesma forma de mensagem.

​
Saídas estruturadas

​
structured_output is None but the result says success

Uma mensagem de resultado pode terminar com subtype: "success" enquanto structured_output é None em Python ou undefined em TypeScript. A execução é concluída, mas nenhuma saída validada existe. Uma maneira de atingir isso é um esquema que nenhuma saída pode satisfazer, por exemplo restrições de comprimento conflitantes. A execução termina sem um erro de validação, e o único sinal é o structured_output ausente. Trate este resultado como uma falha no código da aplicação. Verifique se subtype é success e se structured_output está presente antes de usá-lo. A seção Error handling mostra este padrão para ambos os SDKs. Se isso acontecer repetidamente com um esquema que você acredita estar correto, verifique se o esquema é satisfazível, simplifique-o até que as saídas sejam validadas e reintroduza as restrições uma de cada vez.

​
Relatar um novo problema

Se seu erro não for coberto aqui, verifique os problemas abertos ou abra um novo nos repositórios do SDK: claude-agent-sdk-typescript ou claude-agent-sdk-python. Inclua o texto de erro completo e sua versão do SDK.