Solucionar problemas de instalação e login

Se a instalação falhar ou você não conseguir fazer login, encontre seu erro abaixo. Para problemas de tempo de execução após o Claude Code estar funcionando, consulte Solução de problemas. Para problemas de configuração, como configurações não sendo aplicadas ou hooks não disparando, consulte Depurar sua configuração.

Encontre seu erro

Corresponda a mensagem de erro ou sintoma que você está vendo a uma solução:

O que você vê	Solução
`command not found: claude` ou `'claude' is not recognized`	Corrija seu PATH
`Native installation exists but ... is not in your PATH`	Adicione o diretório de instalação ao seu PATH
`INFO: Could not find files for the given pattern(s).` de `where.exe claude`	Verifique se o Claude Code está instalado
`zsh: permission denied: /Users/you/.zshrc` ou `bash: /home/you/.bashrc: Permission denied`	Torne seu arquivo de configuração do shell gravável
`syntax error near unexpected token '<'`	O script de instalação retorna HTML
`< was unexpected at this time` no CMD	O script de instalação retorna HTML
`The term 'System.Xml.XmlDocument' is not recognized`	O script de instalação retorna HTML
`curl: (22) The requested URL returned error: 403`	O script de instalação retornou 403
`curl: (23)` ou `curl: (56) Failure writing output to destination`	Verifique a conectividade ou use um instalador alternativo
`Killed` durante a instalação no Linux	Libere memória ou adicione espaço de troca
`Installation was killed before it could finish`	Libere memória e execute novamente o instalador
`Raw mode is not supported` durante a instalação	Execute novamente o instalador
`EACCES: permission denied` durante a instalação	Corrija as permissões do diretório de instalação
`TLS connect error` ou `SSL/TLS secure channel`	Atualize os certificados CA
`CRYPT_E_NO_REVOCATION_CHECK` ou `CRYPT_E_REVOCATION_OFFLINE`	Contorne verificações de revogação bloqueadas
`Failed to fetch version` ou não consegue alcançar o servidor de download	Verifique as configurações de rede e proxy
`The connection dropped while downloading the update` ou `Download timed out: exceeded the total deadline`	Execute a atualização novamente ou configure seu proxy
`Release verification failed for Claude Code`	Execute `claude update` ou `claude install` novamente
`Auto-update failed · Run claude doctor` em vermelho no rodapé da sessão	Execute `claude update` a partir do seu shell
`irm is not recognized` ou `The token '&&' is not a valid statement separator`	Use o comando correto para seu shell
`Cask 'claude-code' is unavailable: No Cask with this name exists`	Atualize o Homebrew
`Cask 'claude-code@latest' is not installed`	Atualize o cask que você instalou
`'bash' is not recognized as the name of a cmdlet`	Use o comando do instalador do Windows
`A parameter cannot be found that matches parameter name 'fsSL'`	Use o comando do instalador do Windows
`Claude Code on Windows requires either Git for Windows (for bash) or PowerShell`	Instale um shell
`Claude Code does not support 32-bit Windows`	Abra o Windows PowerShell, não a entrada x86
`The process cannot access the file ... because it is being used by another process`	Limpe a pasta de downloads e tente novamente
`Error loading shared library`	Variante binária incorreta para seu sistema
`Illegal instruction`	Incompatibilidade de arquitetura ou conjunto de instruções da CPU
`cannot execute binary file: Exec format error` em WSL	Regressão de binário nativo WSL1
`Bus error` ou `oh no: Bun has crashed` enquanto uma sessão está em execução	Mantenha o executável legível
O instalador PowerShell é concluído mas `claude` não é encontrado ou mostra uma versão antiga	Adicione o diretório de instalação ao seu PATH, depois abra um novo terminal
`dyld: Symbol not found`, `dyld: cannot load`, ou `Abort trap` no macOS	Incompatibilidade binária
`claude update` trava após `Checking for updates`, ou `claude doctor` trava sem saída	Mova o diretório em um caminho de configuração de shell
`Invoke-Expression` ou `iex` erros de análise citando tags HTML ou CSS, ou `ParserError` com `ParseException`	O script de instalação retorna HTML
`running scripts is disabled on this system` ou `PSSecurityException`	Permita que os shims npm sejam executados
`Error: claude native binary not installed`	Conclua a instalação npm
`npm error code ENOTEMPTY` durante atualização ou reinstalação	Remova o diretório de pacote restante
`'claude' is not recognized` logo após uma atualização no Windows	Restaure `claude.exe` de seu backup
No Windows, o comando de instalação imprime texto de script e nada é instalado	Execute o comando de instalação completo
`App unavailable in region`	Claude Code não está disponível em seu país. Consulte países suportados.
`unable to get local issuer certificate`	Configure certificados CA corporativos
`OAuth error` ou `403 Forbidden`	Corrija a autenticação
`Claude Code access has not been granted for this account`	Obtenha uma função que inclua Claude Code
`Unable to connect to Anthropic services` durante a configuração	Consulte Unable to connect to Anthropic services na referência de erros
`Could not load the default credentials` ou `Could not load credentials from any providers`	Credenciais do Amazon Bedrock, Google Cloud’s Agent Platform ou Microsoft Foundry
`ChainedTokenCredential authentication failed` ou `CredentialUnavailableError`	Credenciais do Amazon Bedrock, Google Cloud’s Agent Platform ou Microsoft Foundry
`API Error: 500`, `529 Overloaded`, `429`, ou outros erros 4xx e 5xx não listados acima	Consulte a referência de erros

Se seu problema não estiver listado, trabalhe através das verificações de diagnóstico abaixo para estreitar a causa.

Se você preferir pular o terminal completamente, o Claude Code Desktop app permite que você instale e use Claude Code através de uma interface gráfica. Baixe-o para macOS ou Windows e comece a codificar sem nenhuma configuração de linha de comando. No Linux, instale o aplicativo com apt seguindo as instruções de instalação do Linux.

Execute verificações de diagnóstico

Verifique a conectividade de rede

O instalador baixa de downloads.claude.ai. Verifique se você consegue alcançá-lo:

macOS/Linux
Windows PowerShell

curl -sI https://downloads.claude.ai/claude-code-releases/latest

curl.exe -sI https://downloads.claude.ai/claude-code-releases/latest

O PowerShell cria um alias de curl para Invoke-WebRequest, que rejeita as flags -sI, então chame curl.exe explicitamente.

Você alcançou o servidor se a primeira linha mostrar um status 200. Você vê HTTP/2 200 no macOS e Linux, e HTTP/1.1 200 OK do curl.exe incluído no Windows. Outros resultados apontam para a causa:

403: geralmente um proxy ou filtro de rede bloqueando o host, ou Claude Code não está disponível em sua região
5xx: geralmente um problema temporário de serviço; aguarde alguns minutos e tente novamente

Se você não vir nenhuma saída, Could not resolve host, ou um timeout de conexão, sua rede está bloqueando a conexão. Causas comuns:

Firewalls corporativos ou proxies bloqueando downloads.claude.ai
Restrições de rede regional: tente uma VPN ou rede alternativa
Problemas de TLS/SSL: atualize os certificados CA do seu sistema, ou verifique se HTTPS_PROXY está configurado

Se você estiver atrás de um proxy corporativo, defina HTTPS_PROXY e HTTP_PROXY para o endereço do seu proxy antes de instalar. Peça à sua equipe de TI pela URL do proxy se você não souber, ou verifique as configurações de proxy do seu navegador. Este exemplo define ambas as variáveis de proxy e executa o instalador através do seu proxy:

macOS/Linux
Windows PowerShell

export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080
curl -fsSL https://claude.ai/install.sh | bash

$env:HTTP_PROXY = 'http://proxy.example.com:8080'
$env:HTTPS_PROXY = 'http://proxy.example.com:8080'
irm https://claude.ai/install.ps1 | iex

Verifique seu PATH

Se a instalação foi bem-sucedida mas você recebe um erro command not found ou not recognized ao executar claude, o diretório de instalação não está em seu PATH. Seu shell procura por programas em diretórios listados em PATH, e o instalador coloca claude em ~/.local/bin/claude no macOS/Linux ou %USERPROFILE%\.local\bin\claude.exe no Windows. O instalador detecta esse caso e o relata em Setup notes: em sua saída: Native installation exists but ~/.local/bin is not in your PATH. no macOS e Linux, ou Native installation exists but C:\Users\you\.local\bin is not in your PATH. no Windows. Ele imprime a correção junto com essa nota, mas não altera o PATH por conta própria.

A extensão VS Code não coloca claude neste local. Ela agrupa uma cópia privada da CLI dentro do diretório da extensão para seu próprio painel de chat e não a adiciona ao PATH. Se você tiver instalado apenas a extensão, ~/.local/bin/claude não existirá. Execute a instalação autônoma para usar claude a partir de um terminal, depois continue abaixo.

Primeiro verifique se o programa está lá, depois verifique se a pasta dele está em seu PATH. A correção do PATH é permanente, então você a aplica uma única vez. Escolha a aba da sua plataforma e execute os comandos dela: no seu terminal no macOS e Linux, ou no PowerShell ou Prompt de Comando no Windows.

macOS/Linux
Windows PowerShell
Windows CMD

Verifique se o instalador colocou o programa no lugar:

ls -la ~/.local/bin/claude

No such file or directory: não há instalação nativa. Se você não instalou o Claude Code de outra forma, como com npm, Homebrew ou um gerenciador de pacotes do Linux, instale o Claude Code. Se você o instalou de outra forma, consulte Verifique se há instalações conflitantes.
Uma listagem do arquivo: o programa está lá. Verifique seu PATH em seguida.

Liste suas entradas de PATH e filtre pela pasta de instalação:

echo $PATH | tr ':' '\n' | grep -Fx "$HOME/.local/bin"

Se isso imprimir /Users/you/.local/bin ou /home/you/.local/bin, o diretório está em seu PATH e você pode pular para Verifique se há instalações conflitantes. Se não houver saída, adicione-o à sua configuração de shell com os dois comandos para o seu shell. O comando echo salva a configuração para todo novo terminal, e source a aplica à janela em que você está. O comando echo não imprime nada quando é bem-sucedido.Para Zsh, o padrão no macOS:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Para Bash no Linux, onde é o padrão na maioria das distribuições:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Para Bash no macOS, adicione a linha a ~/.bash_profile em vez disso. Terminal no macOS inicia Bash como um shell de login, que ignora ~/.bashrc e lê apenas o primeiro de ~/.bash_profile, ~/.bash_login, ou ~/.profile que existe. Se você já tem um ~/.bash_login ou ~/.profile e nenhum ~/.bash_profile, coloque a linha naquele arquivo em vez de criar ~/.bash_profile:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bash_profile
source ~/.bash_profile

Alternativamente, feche e reabra seu terminal.Se o comando echo imprimir permission denied, consulte permission denied ao adicionar ao seu PATH.Para outros shells como fish ou Nushell, adicione ~/.local/bin ao seu PATH usando a sintaxe de configuração do seu próprio shell, depois reinicie seu terminal.Verifique se a correção funcionou:

claude --version

Se claude ainda não for encontrado, verifique estas causas:

O terminal é anterior à alteração: uma janela que já estava aberta mantém seu PATH antigo, e um terminal dentro de um editor recebe seu PATH do editor. Abra uma nova janela, ou feche e reabra o editor.
A linha não foi salva: execute grep -n '.local/bin' ~/.zshrc, usando o nome de arquivo do seu shell. Ele imprime a linha com seu número de linha quando a linha está lá. Se não imprimir nada, execute os dois comandos de PATH novamente.
A linha foi para o arquivo de outro shell: execute echo $0 para ver seu shell e, em seguida, execute os dois comandos de PATH para esse shell.

Verifique se o instalador colocou o programa no lugar:

Test-Path "$env:USERPROFILE\.local\bin\claude.exe"

False: não há instalação nativa. Se você não instalou o Claude Code de outra forma, como com npm ou WinGet, instale o Claude Code. Se você o instalou de outra forma, consulte Verifique se há instalações conflitantes.
True: o programa está lá. Verifique seu PATH em seguida.

Liste suas entradas de PATH e filtre pela pasta de instalação:

$env:PATH -split ';' | Select-String '\.local\\bin'

Se isso imprimir C:\Users\you\.local\bin, o diretório está em seu PATH e você pode pular para Verifique se há instalações conflitantes. Se não houver saída, adicione o diretório de instalação ao seu User PATH:

$currentPath = [Environment]::GetEnvironmentVariable('PATH', 'User')
[Environment]::SetEnvironmentVariable('PATH', "$currentPath;$env:USERPROFILE\.local\bin", 'User')

Reinicie seu terminal para que a alteração tenha efeito.Verifique se a correção funcionou:

claude --version

Se claude ainda não for encontrado em um novo terminal, verifique estas causas:

O terminal é executado dentro de um editor: ele recebe seu PATH do editor, então feche e reabra o editor.
A alteração não foi salva: execute [Environment]::GetEnvironmentVariable('PATH', 'User') e procure por .local\bin no PATH que ele imprime. Se estiver ausente, execute os dois comandos novamente.

Verifique se o instalador colocou o programa no lugar:

dir "%USERPROFILE%\.local\bin\claude.exe"

File Not Found ou The system cannot find the path specified.: não há instalação nativa. Se você não instalou o Claude Code de outra forma, como com npm ou WinGet, instale o Claude Code. Se você o instalou de outra forma, consulte Verifique se há instalações conflitantes.
Uma listagem de claude.exe: o programa está lá. Verifique seu PATH em seguida.

Liste suas entradas de PATH e filtre pela pasta de instalação:

echo %PATH% | findstr /i "local\bin"

Se não houver saída, abra Configurações do Sistema, vá para Variáveis de Ambiente e adicione %USERPROFILE%\.local\bin à sua variável User PATH. Reinicie seu terminal.Verifique se a correção funcionou:

claude --version

Se claude ainda não for encontrado em um novo terminal, um terminal dentro de um editor recebe seu PATH do editor, então feche e reabra o editor também.

Verifique se há instalações conflitantes

Múltiplas instalações do Claude Code podem causar incompatibilidades de versão ou comportamento inesperado. Verifique o que está instalado:

macOS/Linux
Windows PowerShell

Liste todos os binários claude encontrados em seu PATH:

which -a claude

Se isso imprimir claude not found, uma linha no claude in ou nada, nenhum claude está em seu PATH. As próximas verificações mostram se algum está instalado.Verifique os três locais de onde um binário claude pode vir. ~/.local/bin/claude é o instalador nativo, ~/.claude/local/ é uma instalação npm local legada criada por versões antigas do Claude Code, e a lista npm global mostra uma instalação -g:

ls -la ~/.local/bin/claude

Uma instalação nativa mostra um symlink em ~/.local/share/claude/versions/. Um script ou um symlink que você criou por conta própria neste caminho é um inicializador personalizado, que auto-update deixa no lugar.Se algum comando ls imprimir No such file or directory, isso não é um erro. Significa que nada está instalado naquele local, então passe para a próxima verificação.

ls -la ~/.claude/local/

npm -g ls @anthropic-ai/claude-code 2>/dev/null

Se ls -la ~/.local/bin/claude imprimiu No such file or directory, não há instalação nativa. Se você não instalou o Claude Code de outra forma, como com npm, Homebrew ou um gerenciador de pacotes do Linux, instale o Claude Code. Se ~/.local/bin/claude existe mas which -a claude não o listou, a pasta não está em seu PATH: consulte Verifique seu PATH.

Liste todos os binários claude encontrados em seu PATH:

where.exe claude

Se isso imprimir INFO: Could not find files for the given pattern(s)., nenhum claude está em seu PATH.Verifique se o instalador nativo colocou um binário:

Test-Path "$env:USERPROFILE\.local\bin\claude.exe"

True: a instalação nativa está lá. Se where.exe não encontrou nada, a pasta dela não está em seu PATH: consulte Verifique seu PATH.
False: não há instalação nativa. Se você não instalou o Claude Code de outra forma, como com npm ou WinGet, instale o Claude Code.

Se você encontrar múltiplas instalações, mantenha apenas uma. A instalação nativa em ~/.local/bin/claude no macOS/Linux ou %USERPROFILE%\.local\bin\claude.exe no Windows é recomendada. Remova as extras: Desinstale uma instalação npm global:

npm uninstall -g @anthropic-ai/claude-code

Remova a instalação npm local legada:

macOS/Linux
Windows PowerShell

rm -rf ~/.claude/local

Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\local"

Remova uma instalação Homebrew no macOS. Se você instalou o cask claude-code@latest, substitua esse nome:

brew uninstall --cask claude-code

Remova uma instalação WinGet no Windows:

winget uninstall Anthropic.ClaudeCode

Verifique permissões de diretório

Uma instalação que falha por permissões informa o caminho que não conseguiu criar ou gravar. No Windows, a instalação grava em %USERPROFILE%, que é gravável pelo seu usuário por padrão, então esta seção raramente se aplica lá. No macOS e Linux, a instalação grava nestes locais:

~/.claude/downloads/: onde o comando de instalação coloca o binário baixado
~/.local/bin/: o inicializador claude
~/.local/share/claude/: cada versão que ela baixa
~/.local/state/claude/: seus arquivos de bloqueio
~/.cache/claude/: downloads preparados
~/.claude.json: seu arquivo de configuração global, onde o instalador registra o método de instalação

Se você definir XDG_DATA_HOME, XDG_STATE_HOME ou XDG_CACHE_HOME, a instalação usa esses em vez de ~/.local/share, ~/.local/state e ~/.cache. Se você definir CLAUDE_CONFIG_DIR, o arquivo de configuração global fica nesse diretório em vez do seu diretório pessoal. Verifique se os diretórios são graváveis:

test -w ~/.local/bin && echo "writable" || echo "not writable"
test -w ~/.claude && echo "writable" || echo "not writable"

Se algum diretório não for gravável, crie o diretório de instalação e defina seu usuário como proprietário:

sudo mkdir -p ~/.local/bin
sudo chown -R $(whoami) ~/.local

Verifique se o binário funciona

Se claude --version imprime uma versão mas claude falha ou trava na inicialização, execute estas verificações para estreitar a causa. Se claude --version disser comando não encontrado, vá para Verifique seu PATH primeiro; os comandos abaixo assumem que claude está em seu PATH. Confirme que o binário existe e é executável:

macOS/Linux
Windows PowerShell

ls -la "$(command -v claude)"

Get-Command claude | Select-Object Source

No Linux, verifique se há bibliotecas compartilhadas ausentes. Se ldd mostrar bibliotecas ausentes, você pode precisar instalar pacotes do sistema. No Alpine Linux e outras distribuições baseadas em musl, consulte Alpine Linux setup.

ldd "$(command -v claude)" | grep "not found"

Confirme que o binário pode executar:

claude --version

Problemas comuns de instalação

Estes são os problemas de instalação mais frequentemente encontrados e suas soluções.

Install script returns HTML instead of a shell script

O comando de instalação falha com um destes erros quando o que ele baixou não é o script de instalação. Bash ou Zsh: o erro cita a primeira linha da página retornada.

bash: line 1: syntax error near unexpected token `<'
bash: line 1: `<!DOCTYPE html>'

PowerShell, erros de análise: os erros apontam para a página retornada, com iex tentando executar HTML e CSS como PowerShell.

iex : At line:1 char:2310
+ ... igin="anonymous"/><script type="text/javascript">!function(o,c){var n ...
Missing argument in parameter list.
...

A redação varia com a versão do PowerShell e o idioma do sistema: você pode ver Missing expression after unary operator '--' ou um ParserError com ParseException em vez disso. Tags HTML ou CSS no texto citado identificam essa falha. Se você baixar com -OutFile install.ps1 em vez disso, o arquivo salvo é a mesma página da web, então isso também não ajuda. PowerShell, System.Xml.XmlDocument: o erro nomeia esse tipo em vez de citar a página.

System.Xml.XmlDocument : The term 'System.Xml.XmlDocument' is not recognized as the name of a cmdlet, function, script
file, or operable program.

Quando irm consegue analisar a resposta como XML, ele retorna um objeto XML em vez de texto, e iex então tenta executar o nome do tipo desse objeto como um comando. O script de instalação é código PowerShell e não pode ser analisado como XML, então esse erro também significa que a resposta foi algo diferente do script. A redação em torno do nome do tipo varia com a versão do PowerShell e o idioma do sistema, mas System.Xml.XmlDocument em si permanece o mesmo, então procure pelo nome do tipo. CMD: você vê este erro, seguido pelo HTML da página retornada.

< was unexpected at this time.

C:\Users\you><!DOCTYPE html>...

A primeira linha aparece no idioma do seu sistema, então procure o HTML que vem depois dela. Um 403 sem página: dependendo de como a requisição foi roteada, o curl relata um status 403 sem corpo HTML.

curl: (22) The requested URL returned error: 403

Todos esses significam que a URL de instalação retornou uma página da web, um documento XML ou um status de erro em vez do script de instalação. Se a saída de erro citar “App unavailable in region,” Claude Code não está disponível em seu país. Consulte supported countries. Um 403 simples sem corpo frequentemente tem a mesma causa, mas também pode vir de um proxy corporativo ou firewall bloqueando o download. Se você estiver em um país suportado e ainda vir o 403, trabalhe através de Check network connectivity antes de tentar os instaladores alternativos abaixo, já que esses alcançam os mesmos hosts. Caso contrário, isso pode acontecer devido a problemas de rede, roteamento regional ou uma interrupção temporária do serviço. Soluções:

Tente novamente após alguns minutos: o problema é frequentemente temporário. Aguarde e tente o comando original novamente.
Use um método de instalação alternativo: diferentemente de uma instalação nativa, uma instalação via Homebrew ou WinGet não se atualiza automaticamente por padrão. No macOS, instale via Homebrew:
brew install --cask claude-code
No Windows, instale via WinGet:
winget install Anthropic.ClaudeCode
Depois execute claude --version para confirmar: o comando imprime um número de versão como 2.1.211 (Claude Code). Se o shell relatar que claude não foi encontrado, abra uma nova janela de terminal e tente novamente: a sessão em que você instalou mantém seu antigo PATH.

`command not found: claude` after installation

A instalação foi concluída mas claude não funciona. O erro exato varia por plataforma:

Plataforma	Mensagem de erro
macOS	`zsh: command not found: claude`
Linux	`bash: claude: command not found`
Windows CMD	`'claude' is not recognized as an internal or external command`
PowerShell	`claude : The term 'claude' is not recognized as the name of a cmdlet`

No Windows, se o erro começou logo após o Claude Code ser atualizado, consulte restaurar claude.exe a partir do backup. Caso contrário, consulte Verifique seu PATH para a correção em cada plataforma.

`permission denied` when adding to your PATH

Se o comando echo que adiciona ~/.local/bin ao seu PATH imprimir zsh: permission denied: /Users/you/.zshrc ou bash: /home/you/.bashrc: Permission denied, seu usuário não pode escrever nesse arquivo e nada foi salvo. No seu terminal, verifique quem é o proprietário do arquivo, usando o nome do arquivo do seu shell no lugar de ~/.zshrc:

ls -l ~/.zshrc

O terceiro campo da saída é o proprietário.

O proprietário é outro usuário, como root: assuma a propriedade com sudo chown $(whoami) ~/.zshrc, o que requer direitos de administrador.
O proprietário é você: o arquivo é somente leitura. Torne-o gravável com chmod u+w ~/.zshrc.

Depois execute novamente os dois comandos de PATH para o seu shell em Verifique seu PATH.

`curl: (56) Failure writing output to destination`

O comando curl ... | bash baixa o script e o encanua para Bash para execução. Este erro, e o relacionado curl: (23) Failure writing output to destination, significa que Bash não recebeu o script completo. O código de saída 56 indica que o download em si foi interrompido, e o código de saída 23 indica que curl não conseguiu escrever o que recebeu para o pipe, geralmente porque Bash saiu cedo. Teste se você consegue alcançar downloads.claude.ai com a verificação em Check network connectivity. Se você alcançou o servidor, a falha original foi provavelmente intermitente; tente novamente o comando de instalação. Você também pode tentar um método de instalação alternativo.

Homebrew cask unavailable or outdated

Homebrew relata Error: Cask 'claude-code' is unavailable: No Cask with this name exists quando sua cópia local do índice de cask do Homebrew é anterior à publicação do cask. Atualize o índice e tente novamente:

brew update
brew install --cask claude-code

Se Homebrew instalar uma versão mais antiga do Claude Code do que você espera, o mesmo índice desatualizado é geralmente a causa. O cask claude-code rastreia o canal estável e é tipicamente cerca de uma semana atrás da versão mais recente; para a versão mais recente execute brew install --cask claude-code@latest em vez disso. Consulte Configure release channel para a diferença entre os dois casks.

`Cask 'claude-code@latest' is not installed`

O Homebrew oferece dois casks, claude-code e claude-code@latest. Executar brew upgrade --cask claude-code@latest quando esse cask não é o que está instalado imprime Error: Cask 'claude-code@latest' is not installed. Para ver qual cask você tem, execute isto no seu terminal:

brew list --cask | grep claude-code

Atualize o cask que ele imprimir. Se não imprimir nada, nenhum dos casks está instalado.

TLS or SSL connection errors

Erros como estes significam que o handshake TLS falhou:

curl: (35) TLS connect error
schannel: next InitializeSecurityContext failed
PowerShell’s Could not create SSL/TLS secure channel
PowerShell’s Could not establish trust relationship for the SSL/TLS secure channel

Para CRYPT_E_NO_REVOCATION_CHECK ou CRYPT_E_REVOCATION_OFFLINE, vá para a etapa 4. Soluções:

Atualize seus certificados CA do sistema: No Ubuntu/Debian:
sudo apt-get update && sudo apt-get install ca-certificates
No macOS, o curl do sistema usa o armazenamento de confiança do Keychain; atualizar o macOS em si atualiza os certificados raiz.

No Windows PowerShell 5.1, ative TLS 1.2:

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

Depois execute o instalador na mesma janela:

irm https://claude.ai/install.ps1 | iex

Verifique se há interferência de proxy ou firewall: proxies corporativos que realizam inspeção TLS podem causar esses erros, incluindo unable to get local issuer certificate e SELF_SIGNED_CERT_IN_CHAIN. Para a etapa de instalação, faça o download de instalação confiar no CA do seu proxy corporativo:
- macOS/Linux
- Windows PowerShell
curl --cacert /path/to/corporate-ca.pem -fsSL https://claude.ai/install.sh | bash
O instalador PowerShell baixa através do .NET, que valida TLS contra o armazenamento de certificados do Windows. Peça à sua equipe de TI para adicionar o certificado CA do proxy ao armazenamento do Windows se ainda não estiver lá, depois execute o instalador:
irm https://claude.ai/install.ps1 | iex
Para o Claude Code em si uma vez instalado, defina NODE_EXTRA_CA_CERTS para que as requisições de API confiem no mesmo pacote:
- macOS/Linux
- Windows PowerShell
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem
$env:NODE_EXTRA_CA_CERTS = 'C:\path\to\corporate-ca.pem'
Peça à sua equipe de TI pelo arquivo de certificado se você não tiver. Você também pode tentar em uma conexão direta para confirmar que o proxy é a causa.
No Windows, contorne verificações de revogação bloqueadas. Os erros CRYPT_E_NO_REVOCATION_CHECK (0x80092012) e CRYPT_E_REVOCATION_OFFLINE (0x80092013) significam que curl alcançou o servidor mas sua rede bloqueia a pesquisa de revogação de certificado, o que é comum atrás de firewalls corporativos. Se o comando que está falhando é o curl que baixa install.cmd, execute-o novamente de um Prompt de Comando com --ssl-revoke-best-effort adicionado:
curl --ssl-revoke-best-effort -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
Quando os downloads do próprio script atingem os mesmos erros, ele os tenta novamente com verificação de revogação de melhor esforço automaticamente, então a flag é necessária apenas no comando que você executa. A verificação de melhor esforço tolera um servidor de revogação inacessível mas ainda rejeita um certificado que é conhecido por ser revogado, correspondendo a como os navegadores lidam com revogação. Você também pode evitar completamente a verificação de revogação do curl executando o instalador PowerShell do PowerShell, que baixa através do .NET e não falha quando o servidor de revogação está inacessível:
irm https://claude.ai/install.ps1 | iex
Você também pode instalar com winget install Anthropic.ClaudeCode, que evita curl completamente.

`Failed to fetch version from downloads.claude.ai`

O instalador não conseguiu alcançar o servidor de download. Isso normalmente significa que downloads.claude.ai está bloqueado em sua rede. Consulte Check network connectivity.

The connection dropped while downloading the update

A conexão com o servidor de download foi encerrada enquanto claude install ou claude update baixava o binário do Claude Code, e as novas tentativas não se recuperaram. O Claude Code tenta novamente o download quando a conexão cai, a transferência trava ou o arquivo baixado falha na verificação de checksum, até três tentativas no total. Um erro HTTP concluído, como um 404, não gera nova tentativa porque o servidor já respondeu. Antes da v2.1.202, uma única queda de conexão fazia o download falhar imediatamente com o erro simples aborted em vez de tentar novamente.

The connection dropped while downloading the update (attempt 3/3: aborted). Check your network — proxies sometimes cut off large downloads.

O texto entre parênteses indica qual tentativa falhou e o erro de rede subjacente. claude update precede a mensagem com Error: Failed to install native update no stderr. Um download que permanece conectado mas não termina em 10 minutos falha com Download timed out: exceeded the total deadline em vez disso. O Claude Code não tenta novamente um download que excedeu o tempo limite, porque uma conexão lenta demais para terminar dentro do prazo também não terminará em uma nova tentativa imediata. As etapas abaixo se aplicam às duas mensagens. Um proxy ou gateway pode encerrar uma transferência longa antes que ela termine, e o binário do Claude Code é um download grande. O que fazer:

Execute claude update novamente. Em uma rede de resto saudável, o download geralmente é bem-sucedido na próxima execução. Para a mensagem de tempo limite excedido, execute-o novamente a partir de uma rede mais rápida ou menos limitada.
Se sua rede exigir um proxy, defina HTTPS_PROXY antes de executar o instalador ou claude update. Consulte Check network connectivity.
Se um proxy corporativo continuar encerrando a transferência, peça à sua equipe de rede para permitir o download completo de downloads.claude.ai. Consulte Network access requirements.
Execute claude doctor no seu shell para obter diagnósticos de instalação

Release verification failed for Claude Code

Esta mensagem de claude update ou claude install significa que o Claude Code não conseguiu confirmar que a versão que estava prestes a instalar é genuína, então não instalou nada. Qualquer versão que você já tenha continua funcionando.

Release verification failed for Claude Code <version> (<reason>). The update was not installed.

Siga a etapa que corresponde ao valor entre parênteses na sua mensagem:

Um valor que começa com sidecar_fetch_: execute o mesmo comando novamente a partir do seu shell. claude update foi bem-sucedido se imprimir uma linha que começa com Successfully updated from, e claude install foi bem-sucedido se imprimir Claude Code successfully installed!.
Qualquer outro valor: tente o mesmo comando novamente mais tarde

Com qualquer valor, se a mensagem se repetir, relate o problema e inclua a mensagem completa.

`Auto-update failed · Run claude doctor` in the session footer

Esta linha vermelha significa que o Claude Code tentou se atualizar em segundo plano e a atualização não foi instalada. Você pode continuar trabalhando sem fazer nada. A linha indica claude doctor, cuja linha Last update attempt: failed (install_failed) mostra uma data, mas não a causa. Para concluir a atualização ou ver por que ela falhou, execute claude update no seu shell em vez disso. Se essa instalação também falhar, procure o erro que claude update imprime em Encontre seu erro.

Wrong install command on Windows

Se você vir 'irm' is not recognized, The token '&&' is not a valid statement separator, A parameter cannot be found that matches parameter name 'fsSL', ou 'bash' is not recognized as the name of a cmdlet, você copiou o comando de instalação para um shell ou sistema operacional diferente. Se o comando imprimir o texto do script em vez de instalar qualquer coisa, você executou apenas parte dele.

irm não reconhecido: você está em CMD, não PowerShell. Você tem duas opções: Abra PowerShell procurando por “PowerShell” no menu Iniciar, depois execute o comando de instalação original:
irm https://claude.ai/install.ps1 | iex
Ou fique em CMD e use o instalador CMD em vez disso:
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd
&& não é um separador de instrução válido: você está em PowerShell mas executou o comando do instalador CMD. Use o instalador PowerShell:
irm https://claude.ai/install.ps1 | iex
A parameter cannot be found that matches parameter name 'fsSL': você executou o instalador macOS/Linux curl -fsSL ... | bash no Windows PowerShell, onde curl é um alias para Invoke-WebRequest e rejeita as flags -fsSL. Use o instalador PowerShell em vez disso:
irm https://claude.ai/install.ps1 | iex
bash não reconhecido: você executou o instalador macOS/Linux no Windows. Use o instalador PowerShell em vez disso:
irm https://claude.ai/install.ps1 | iex
O comando imprime texto do script em vez de instalar: você executou a metade do download do comando sem a parte que o executa. irm https://claude.ai/install.ps1 por si só imprime o script baixado para o terminal. Canalize-o para iex para executá-lo:
irm https://claude.ai/install.ps1 | iex
Em CMD, curl -fsSL https://claude.ai/install.cmd sem -o imprime o script em lote em vez de salvá-lo. Execute o comando completo:
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Qualquer que seja o instalador que você use, confirme que funcionou: abra um novo terminal e execute claude --version, que imprime um número de versão como 2.1.211 (Claude Code).

`running scripts is disabled on this system`

Instalar ou executar Claude Code através de npm no Windows pode falhar com um SecurityError:

npm : File C:\Program Files\nodejs\npm.ps1 cannot be loaded because running scripts is disabled on this system. For more information, see about_Execution_Policies at https:/go.microsoft.com/fwlink/?LinkID=135170.
...
    + CategoryInfo          : SecurityError: (:) [], PSSecurityException

O mesmo erro nomeia claude.ps1 quando você executa claude após uma instalação npm. A política de execução do PowerShell está bloqueando os scripts de inicializador .ps1 que npm cria para seus comandos. A política se aplica a arquivos de script, então não afeta o instalador PowerShell irm https://claude.ai/install.ps1 | iex, que executa o texto baixado diretamente. Soluções:

Permita scripts criados localmente para seu usuário, depois tente novamente:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Chame o inicializador .cmd em vez disso: npm.cmd e claude.cmd fazem o mesmo trabalho, e a política não os cobre.
Use o PowerShell installer em vez de npm. Ele instala um binário em vez de um script .ps1.

`The process cannot access the file` during Windows install

Se o instalador PowerShell falhar com Failed to download binary: The process cannot access the file ... because it is being used by another process, o instalador não conseguiu escrever em %USERPROFILE%\.claude\downloads. Isso geralmente significa que uma tentativa de instalação anterior ainda está em execução, ou o software antivírus está verificando um binário parcialmente baixado nessa pasta. Feche qualquer outra janela do PowerShell executando o instalador e aguarde as verificações de antivírus liberarem o arquivo. Depois delete a pasta de downloads e execute o instalador novamente:

Remove-Item -Recurse -Force "$env:USERPROFILE\.claude\downloads"
irm https://claude.ai/install.ps1 | iex

`claude.exe` missing after an update on Windows

Se seu terminal relatar 'claude' is not recognized logo após Claude Code atualizar no Windows, verifique se %USERPROFILE%\.local\bin ainda contém claude.exe. Se esse diretório não estiver em seu PATH de forma alguma, consulte Verifique seu PATH em vez disso. Para atualizar no Windows, Claude Code renomeia o claude.exe existente para um backup e move a nova versão para seu lugar. Se mover a nova versão para seu lugar falhar e Claude Code não conseguir renomear o backup de volta, o diretório mantém o backup mas não tem claude.exe. O backup é um arquivo no mesmo diretório cujo nome começa com claude.exe.old. seguido por um timestamp numérico. Execute o seguinte no PowerShell para renomear o backup mais recente de volta para claude.exe:

Get-ChildItem "$env:USERPROFILE\.local\bin\claude.exe.old.*" | Sort-Object Name | Select-Object -Last 1 | Rename-Item -NewName claude.exe

Depois execute claude --version para confirmar a correção. Um claude.exe restaurado imprime um número de versão. Se não houver arquivo claude.exe.old.*, ou claude ainda falhar após a renomeação, reinstale em vez disso:

irm https://claude.ai/install.ps1 | iex

Antes da v2.1.281, Claude Code poderia deletar o backup enquanto claude.exe ainda estava faltando.

Install killed on low-memory Linux servers

Uma mensagem Killed durante a instalação geralmente significa que o assassino de falta de memória (OOM) do Linux encerrou a etapa claude install porque o sistema ficou sem memória livre. Isso é comum em VPS pequenos e instâncias em nuvem. O script de instalação relata a causa e sai com código 137. Neste exemplo, o número da linha e o ID do processo variam por versão e execução:

Setting up Claude Code...
bash: line 183: 34803 Killed    "$binary_path" install ${TARGET:+"$TARGET"}
Installation was killed before it could finish (exit code 137). This usually means the system ran out of memory.
Claude Code needs roughly 512MB of free memory to install. Free up memory, then run this script again.

A instalação precisa de aproximadamente 512 MB de memória livre, e executar Claude Code precisa de mais. Consulte os system requirements. Soluções:

Adicione espaço de swap se seu servidor tiver RAM limitada. Swap usa espaço em disco como memória de overflow, permitindo que a instalação seja concluída mesmo com RAM física baixa. Crie um arquivo de swap de 2 GB e ative-o:
sudo fallocate -l 2G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile
Depois tente a instalação novamente:
curl -fsSL https://claude.ai/install.sh | bash
Feche outros processos para liberar memória antes de instalar.
Use uma instância maior se possível. Claude Code requer pelo menos 4 GB de RAM.

Installation was killed before it could finish

O script de instalação informa quando a etapa claude install é encerrada por um sinal. No Linux, o código de saída 137 significa que o processo recebeu SIGKILL e, em um host com pouca memória, geralmente é o assassino de falta de memória (OOM) do kernel. O script imprime esta explicação e sai com código 137:

Installation was killed before it could finish (exit code 137). This usually means the system ran out of memory.
Claude Code needs roughly 512MB of free memory to install. Free up memory, then run this script again.

Para qualquer outro sinal fatal, e para o código de saída 137 no macOS, o script imprime Installation was killed before it could finish (exit code <N>) com o código de saída real e omite a explicação sobre falta de memória. A mensagem vem do script de instalação que o macOS e o Linux usam, que também abrange instalações dentro do WSL; os scripts de instalação nativos do Windows nunca a imprimem. Antes da v2.1.200, o script saía apenas com a linha simples Killed do shell. O que fazer:

Encerre outros processos para liberar memória e depois execute o instalador novamente
Adicione espaço de swap ou mude para uma instância maior. Consulte Install killed on low-memory Linux servers para os comandos do arquivo de swap.

Install hangs in Docker

Ao instalar Claude Code em um contêiner Docker, instalar como root em / pode causar travamentos. Soluções:

Defina um diretório de trabalho antes de executar o instalador. Quando executado de /, o instalador verifica todo o sistema de arquivos, o que causa uso excessivo de memória. Definir WORKDIR limita a verificação a um pequeno diretório:
WORKDIR /tmp RUN curl -fsSL https://claude.ai/install.sh | bash
Aumente a memória do Docker se usar Docker Desktop. Os contêineres de build compartilham a memória alocada para a máquina virtual do Docker Desktop, então abra Settings > Resources no Docker Desktop, aumente o limite de memória e execute o build novamente.

`Raw mode is not supported` during install

Quando as server-managed settings da sua organização incluem alterações que precisam de security approval, versões do Claude Code anteriores a 2.1.246 tentam mostrar o diálogo de aprovação durante claude install. O diálogo precisa de um terminal em stdin. Quando o instalador executa claude install de um pipe, como curl -fsSL https://claude.ai/install.sh | bash faz, stdin é o pipe em vez de um terminal, então a instalação falha com um erro contendo Raw mode is not supported. Claude Code v2.1.246 e posterior não mostram o diálogo durante claude install ou claude update. O comando é executado com as configurações que você aprovou pela última vez, e Claude Code mostra o diálogo em sua próxima sessão interativa. Se a configuração de inicialização da sua organização aguarda a busca de configurações, como quando define forceRemoteSettingsRefresh, o diálogo ainda aparece durante esses comandos, e uma execução de instalação de um pipe ainda falha. Em todas as outras configurações, executar novamente o instalador passa por esse erro, porque o script executa o comando install da versão mais recente mesmo quando você pede para instalar uma versão mais antiga. Execute novamente o comando para sua plataforma:

macOS/Linux
Windows PowerShell

curl -fsSL https://claude.ai/install.sh | bash

irm https://claude.ai/install.ps1 | iex

claude --version imprime a versão que a execução novamente instalou.

`claude update` or `claude doctor` hangs

claude update e claude doctor verificam seus arquivos de configuração de shell para um alias claude desatualizado: ~/.zshrc, ~/.bashrc e ~/.config/fish/config.fish, além no macOS o primeiro de ~/.bash_profile, ~/.bash_login ou ~/.profile que existe. Se você definir ZDOTDIR, o arquivo Zsh é $ZDOTDIR/.zshrc em vez disso. Quando um desses caminhos é um diretório, Claude Code o ignora e ambos os comandos são concluídos normalmente. Antes da v2.1.214, um diretório em um desses caminhos fazia ambos os comandos travarem e deixava a seção System diagnostics de /status em branco. claude doctor travava sem saída; claude update travava logo após imprimir Checking for updates. Se você atingir o travamento em uma versão anterior, encontre o diretório. Na saída deste comando, uma linha começando com d marca esse caminho como um diretório. Uma linha No such file or directory significa que nada existe nesse caminho e não é a causa:

ls -ld ~/.zshrc ~/.bashrc ~/.bash_profile ~/.bash_login ~/.profile ~/.config/fish/config.fish

Mova o diretório para o lado, ou atualize para v2.1.214 ou posterior. Como claude update trava nas versões afetadas, atualize executando novamente o install script em vez disso.

Claude Desktop overrides the `claude` command on Windows

Se você instalou uma versão mais antiga do Claude Desktop, ele pode registrar um Claude.exe no diretório WindowsApps que tem prioridade de PATH sobre Claude Code CLI. Executar claude abre o aplicativo Desktop em vez do CLI. Atualize Claude Desktop para a versão mais recente para corrigir este problema.

Claude Code on Windows requires either Git for Windows (for bash) or PowerShell

Git for Windows é opcional. Claude Code usa a PowerShell tool quando Git Bash está ausente, então este erro significa que nenhum shell foi encontrado. Se PowerShell estiver faltando do seu PATH, sua localização padrão é C:\Windows\System32\WindowsPowerShell\v1.0\. Adicione esse diretório ao seu PATH, ou instale PowerShell 7, que fornece pwsh. Para instalar Git for Windows em vez disso, baixe de git-scm.com/downloads/win. Durante a configuração, selecione “Add to PATH.” Reinicie seu terminal após instalar. Instalá-lo ativa a ferramenta Bash, útil ao trabalhar com scripts e ferramentas baseadas em Bash. Se Git já estiver instalado mas Claude Code não conseguir encontrá-lo, compare sua localização contra os lugares que Claude Code verifica. Quando CLAUDE_CODE_GIT_BASH_PATH não está definido, Claude Code procura por bash.exe nesta ordem:

Os locais de instalação padrão C:\Program Files\Git e C:\Program Files (x86)\Git.
O git em seu PATH, usando o bin\bash.exe dessa instalação do Git.

Na etapa 2, Claude Code ignora um git que fica na pasta de onde você iniciou Claude Code, ou abaixo dela em um caminho que contém node_modules ou uma pasta de ambiente virtual como .venv ou env, por exemplo C:\dev\env\myproject\Git quando você iniciou de C:\dev\env\myproject. Isso impede que Claude Code execute um executável que um projeto colocou lá. Se seu Git estiver em um local assim, aponte CLAUDE_CODE_GIT_BASH_PATH para ele. Para apontar Claude Code para uma instalação específica do Git, encontre-a executando where.exe git no PowerShell, depois defina o caminho bin\bash.exe dessa instalação como CLAUDE_CODE_GIT_BASH_PATH em seu settings.json file:

{
  "env": {
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  }
}

Se CLAUDE_CODE_GIT_BASH_PATH estiver definido para o caminho correto e o arquivo existir mas Claude Code ainda não o usar, verifique o nome do arquivo primeiro. Claude Code aceita apenas um arquivo nomeado bash.exe, sh.exe, bash ou sh; com qualquer outro nome, como o inicializador git-bash.exe do Git for Windows, ele ignora a variável e auto-detecta Git Bash como se não estivesse definida, registrando um aviso visível com --debug. Um caminho que não existe recebe o mesmo fallback e aviso. Antes da v2.1.219, Claude Code usava qualquer arquivo existente como o shell sem verificar seu nome, e saía na inicialização com Claude Code was unable to find CLAUDE_CODE_GIT_BASH_PATH path quando o caminho não existia. Se o nome do arquivo estiver correto, software de segurança de endpoint como AppLocker, políticas de restrição de software de Política de Grupo ou agentes EDR podem estar interferindo. Peça à sua equipe de TI para adicionar à allowlist claude.exe e os processos que ele gera, incluindo cmd.exe e bash.exe, em sua política de proteção de endpoint.

Claude Code does not support 32-bit Windows

O Windows inclui duas entradas do PowerShell no menu Iniciar: Windows PowerShell e Windows PowerShell (x86). A entrada x86 é executada como um processo de 32 bits e dispara este erro mesmo em uma máquina de 64 bits. Para verificar qual caso você está, execute isto na mesma janela que produziu o erro:

[Environment]::Is64BitOperatingSystem

Se isso imprimir True, seu sistema operacional está bem. Feche a janela, abra Windows PowerShell sem o sufixo x86 e execute o comando de instalação novamente. Se isso imprimir False, você está em uma edição de 32 bits do Windows. Claude Code requer um sistema operacional de 64 bits. Consulte os system requirements.

Linux musl or glibc binary mismatch

Se você vir erros sobre bibliotecas compartilhadas ausentes como libstdc++.so.6 ou libgcc_s.so.1 após a instalação, o instalador pode ter baixado a variante binária errada para seu sistema.

Error loading shared library libstdc++.so.6: No such file or directory

Isso pode acontecer em sistemas baseados em glibc que têm pacotes de compilação cruzada musl instalados, fazendo o instalador detectar incorretamente o sistema como musl. Soluções:

Verifique qual libc seu sistema usa:
ldd --version 2>&1 | head -1
A saída mencionando GNU libc ou GLIBC significa glibc. A saída mencionando musl significa musl.
Se você estiver em glibc mas recebeu o binário musl, remova a instalação e reinstale. Você também pode baixar manualmente o binário correto usando o manifesto em https://downloads.claude.ai/claude-code-releases/{VERSION}/manifest.json. Abra um GitHub issue com a saída de ldd --version e ls /lib/libc.musl*.
Se você estiver realmente em musl, como Alpine Linux, instale os pacotes necessários:
apk add libgcc libstdc++ ripgrep
No Alpine, ripgrep está no repositório community. Se apk relatar que o pacote está faltando, consulte Alpine Linux setup.

`Illegal instruction`

Se executar claude ou o instalador imprimir Illegal instruction, o binário nativo usa instruções de CPU que seu processador não suporta. Existem duas causas distintas. Incompatibilidade de arquitetura. O instalador baixou o binário errado, por exemplo x86 em um servidor ARM. Verifique com uname -m no macOS ou Linux, ou $env:PROCESSOR_ARCHITECTURE no PowerShell. Se o resultado não corresponder ao binário que você recebeu, abra um GitHub issue com a saída. Conjunto de instruções AVX ausente. Se sua arquitetura estiver correta mas você ainda vir Illegal instruction, seu CPU provavelmente não tem AVX ou outra instrução que o binário requer. Isso afeta aproximadamente processadores Intel e AMD anteriores a 2013, e máquinas virtuais onde o hipervisor não passa AVX para o convidado. Em um VPS ou VM, execute grep -m1 -ow avx /proc/cpuinfo; um resultado vazio significa que AVX não está disponível para o convidado. Não há solução alternativa de binário nativo; acompanhe issue #50384 para status e inclua seu modelo de CPU de grep -m1 "model name" /proc/cpuinfo no Linux ou sysctl -n machdep.cpu.brand_string no macOS ao relatar. Métodos de instalação alternativos baixam o mesmo binário nativo e não resolverão nenhuma das causas.

`dyld: cannot load` on macOS

Se você vir dyld: Symbol not found, dyld: cannot load ou Abort trap: 6 durante a instalação, o binário é incompatível com sua versão ou hardware do macOS. Um erro Symbol not found que referencia libicucore significa que sua versão do macOS é mais antiga do que o binário suporta:

dyld: Symbol not found: _ubrk_clone
  Referenced from: claude-darwin-x64 (which was built for Mac OS X 13.0)
  Expected in: /usr/lib/libicucore.A.dylib

O carregador pode em vez disso rejeitar os comandos de carregamento do binário, o que também significa que sua versão do macOS é muito antiga:

dyld: cannot load 'claude-2.1.42-darwin-x64' (load command 0x80000034 is unknown)
Abort trap: 6

Soluções:

Verifique sua versão do macOS: Claude Code requer macOS 13.0 ou posterior. Abra o menu Apple e selecione About This Mac para verificar sua versão.
Atualize o macOS se você estiver em uma versão mais antiga. O binário usa comandos de carregamento e bibliotecas do sistema que versões mais antigas do macOS não suportam. Métodos de instalação alternativos como Homebrew baixam o mesmo binário e não resolverão este erro.

`Bus error` while a session is running

Se uma sessão em execução for encerrada e seu shell imprimir Bus error, uma causa possível é que Claude Code não conseguiu mais ler seu próprio arquivo executável do disco. Por exemplo, o arquivo foi truncado, ou excluído no armazenamento de rede, enquanto a sessão estava em execução. Antes da mensagem do shell, o runtime do Claude Code pode imprimir um relatório de falha que inclui panic(main thread): Bus error at address e oh no: Bun has crashed. This indicates a bug in Bun, not your code. Quando o executável se tornou ilegível, a falha vem do arquivo ilegível, não de um bug no Bun. O relatório também pode estar ausente, se o runtime também não conseguiu ler o código que o imprime. Inicie uma nova sessão para continuar. Se Claude Code estiver instalado em armazenamento de rede, siga Instalar em armazenamento de rede para que as atualizações não removam um binário de que sessões em execução ainda precisam.

`Exec format error` on WSL1

Se executar claude em WSL imprimir cannot execute binary file: Exec format error, você está em WSL1 e atingindo uma regressão de binário nativo conhecida rastreada em issue #38788. Os cabeçalhos do programa do binário mudaram de uma forma que o carregador do WSL1 não consegue lidar. A correção mais limpa é converter sua distribuição para WSL2 do PowerShell:

wsl --set-version <DistroName> 2

Se você precisar ficar em WSL1, invoque o binário através do vinculador dinâmico. Adicione esta função a ~/.bashrc dentro do WSL, substituindo o caminho se seu diretório pessoal for diferente:

claude() {
  /lib64/ld-linux-x86-64.so.2 "$(readlink -f "$HOME/.local/bin/claude")" "$@"
}

Depois execute source ~/.bashrc e tente novamente claude.

npm install errors in WSL

Estes problemas se aplicam se você instalou Claude Code com npm install -g dentro do WSL. Se você usou o native installer, pule esta seção. Problemas de detecção de SO ou plataforma. Se npm relatar uma incompatibilidade de plataforma durante a instalação, WSL provavelmente está pegando o npm do Windows. Execute npm config set os linux primeiro, depois instale com npm install -g @anthropic-ai/claude-code --force. Não use sudo. exec: node: not found ao executar claude. Seu ambiente WSL provavelmente está usando a instalação do Windows do Node.js. Confirme com which npm e which node: caminhos começando com /mnt/c/ são binários do Windows, enquanto caminhos Linux começam com /usr/. Para corrigir isso, instale Node via gerenciador de pacotes da sua distribuição Linux ou via nvm. Conflitos de versão nvm. Se você tiver nvm instalado tanto em WSL quanto em Windows, alternar versões do Node em WSL pode quebrar porque WSL importa o PATH do Windows por padrão e o nvm do Windows tem prioridade. A causa mais comum é que nvm não está carregado em seu shell. Adicione o carregador nvm a ~/.bashrc ou ~/.zshrc:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"

Ou carregue-o em sua sessão atual:

source ~/.nvm/nvm.sh

Se nvm está carregado mas caminhos do Windows ainda têm prioridade, coloque explicitamente seu caminho do Node Linux:

export PATH="$HOME/.nvm/versions/node/$(node -v)/bin:$PATH"

Evite desabilitar a importação de PATH do Windows via appendWindowsPath = false pois isso quebra a capacidade de chamar executáveis do Windows do WSL. Da mesma forma, evite desinstalar Node.js do Windows se você o usa para desenvolvimento do Windows.

Permission errors during installation

Se o instalador nativo falhar com erros de permissão, o diretório de destino pode não ser gravável. Consulte Check directory permissions. Se você instalou anteriormente com npm e está atingindo erros de permissão específicos do npm, mude para o instalador nativo:

curl -fsSL https://claude.ai/install.sh | bash

Native binary not found after npm install

O pacote npm @anthropic-ai/claude-code baixa o binário nativo como uma dependência opcional por plataforma, como @anthropic-ai/claude-code-darwin-arm64. npm então executa o script postinstall do pacote, que copia esse binário no lugar como o comando claude; até que seja executado, claude é um script de espaço reservado. Se o download ou a etapa postinstall for ignorada, o espaço reservado permanece no lugar, e executar claude no macOS e Linux imprime:

Error: claude native binary not installed.

Either postinstall did not run (--ignore-scripts, some pnpm configs)
or the platform-native optional dependency was not downloaded
(--omit=optional).

Run the postinstall manually (adjust path for local vs global install):
  node node_modules/@anthropic-ai/claude-code/install.cjs

Or reinstall without --ignore-scripts / --omit=optional.

No Windows, bin/claude.exe é esse mesmo espaço reservado de script de shell em vez de um executável real, então PowerShell e CMD relatam que não conseguem executar o arquivo em vez de imprimir esta mensagem. Verifique as seguintes causas:

Dependências opcionais estão desabilitadas. Remova --omit=optional do seu comando npm install, --no-optional do pnpm, ou --ignore-optional do yarn, e verifique que .npmrc não define optional=false. Depois reinstale. O binário nativo é entregue apenas como uma dependência opcional, então não há fallback JavaScript se for ignorado, e executar install.cjs novamente não consegue colocar um binário que nunca foi baixado.
Scripts de instalação estão desabilitados. --ignore-scripts e algumas configurações pnpm ignoram a etapa postinstall mas ainda baixam o pacote de plataforma. Execute node node_modules/@anthropic-ai/claude-code/install.cjs como a mensagem sugere, ou reinstale sem a flag. Se postinstall não conseguir executar em seu ambiente, node node_modules/@anthropic-ai/claude-code/cli-wrapper.cjs encontra o pacote baixado e o inicia, ao custo de um processo Node extra em cada inicialização. Se o wrapper imprimir Could not find native binary package em vez disso, o pacote de plataforma nunca foi baixado, então corrija a causa de dependências opcionais acima primeiro.
Plataforma não suportada. Binários pré-compilados são publicados para darwin-arm64, darwin-x64, linux-x64, linux-arm64, linux-x64-musl, linux-arm64-musl, win32-x64 e win32-arm64. Claude Code não envia um binário para outras plataformas; consulte os system requirements. No FreeBSD, o instalador relata a plataforma como não suportada. Antes da v2.1.205, ele tratava FreeBSD como Linux e baixava um binário que não conseguia executar.
Espelho npm corporativo está faltando os pacotes de plataforma. Certifique-se de que seu registro espelha todos os oito pacotes @anthropic-ai/claude-code-* de plataforma além do pacote meta.

npm `ENOTEMPTY` error during update or reinstall

Quando você executa npm install -g @anthropic-ai/claude-code sobre uma instalação existente, npm pode falhar ao mover o diretório do pacote antigo para o lado:

npm error code ENOTEMPTY
npm error syscall rename
npm error path /home/you/.nvm/versions/node/v22.13.1/lib/node_modules/@anthropic-ai/claude-code
npm error dest /home/you/.nvm/versions/node/v22.13.1/lib/node_modules/@anthropic-ai/.claude-code-tVWAnUUt
npm error errno -39
npm error ENOTEMPTY: directory not empty, rename '...'

A linha npm error path nomeia o diretório que npm não conseguiu mover. Delete esse diretório e qualquer diretório .claude-code-* restante ao lado dele, que execuções anteriores interrompidas podem deixar para trás. Os comandos abaixo encontram seu diretório de pacote global com npm root -g; se o diretório que a linha npm error path nomeia não estiver sob o diretório que npm root -g imprime, por exemplo porque você alternou versões do Node com nvm, delete os diretórios que o erro nomeia em vez disso:

macOS/Linux
Windows PowerShell

rm -rf "$(npm root -g)/@anthropic-ai/claude-code"

Depois remova qualquer diretório temporário restante. Se Zsh imprimir no matches found, não havia nenhum para remover:

rm -rf "$(npm root -g)/@anthropic-ai/.claude-code-"*

Remove-Item -Recurse -Force "$(npm root -g)/@anthropic-ai/claude-code", "$(npm root -g)/@anthropic-ai/.claude-code-*"

Depois reinstale:

npm install -g @anthropic-ai/claude-code

Confirme com claude --version, que imprime um número de versão como 2.1.211 (Claude Code). Estas seções abordam falhas de login, erros OAuth e problemas de token. Quando o login falha e a causa não é óbvia, uma re-autenticação limpa resolve a maioria dos casos:

Execute /logout para sair completamente
Feche Claude Code
Reinicie com claude e complete o processo de autenticação novamente

Se o navegador não abrir automaticamente durante o login, pressione c para copiar a URL OAuth para sua área de transferência e depois cole-a em um navegador manualmente. Isso também funciona quando a URL se estende por várias linhas em um terminal estreito ou SSH e não pode ser clicada diretamente.

OAuth error: Invalid code

Se você vir OAuth error: Invalid code. Please make sure the full code was copied, o código de login expirou ou foi truncado durante cópia e cola. Soluções:

Pressione Enter para tentar novamente e complete o login rapidamente após o navegador abrir
Digite c para copiar a URL completa se o navegador não abrir automaticamente
Se usar uma sessão remota/SSH, o navegador pode abrir na máquina errada. Copie a URL exibida no terminal e abra-a em seu navegador local em vez disso.

Se você vir API Error: 403 Request not allowed após fazer login:

Usuários Claude Pro/Max: verifique se sua assinatura está ativa em claude.ai/settings
Usuários do Anthropic Console: confirme que sua conta tem a função “Claude Code” ou “Developer”. Os administradores atribuem isso na página Members do Console em platform.claude.com/settings/members.
Atrás de um proxy: proxies corporativos podem interferir com requisições de API. Consulte network configuration para configuração de proxy.

Claude Code access has not been granted for this account

Se a página de login mostrar Authorization failed com a mensagem Claude Code access has not been granted for this account. Contact your administrator. após você fazer login a partir do Claude Code, sua organização Claude Enterprise definiu sua função como Custom e nenhuma das custom roles atribuídas aos seus grupos concede Claude Code. Na função Custom, você obtém acesso apenas dessas funções personalizadas, portanto nada que você altere no Claude Code resolve esse erro. Para obter acesso:

Peça a um Owner de sua organização Claude para atribuir uma função personalizada que conceda acesso ao Claude Code a um de seus grupos, ou para alterar sua função de Custom para uma função padrão como User. Os Owners gerenciam funções nas role settings da organização.
Após o Owner fazer a alteração, execute claude e faça login novamente.

This organization has been disabled with an active subscription

Se você vir API Error: 400 ... "This organization has been disabled" apesar de ter uma assinatura Claude ativa, uma variável de ambiente ANTHROPIC_API_KEY está substituindo sua assinatura. Isso comumente acontece quando uma chave de API antiga de um empregador anterior ou projeto ainda está definida em seu perfil de shell. Quando ANTHROPIC_API_KEY está presente e você a aprovou, Claude Code usa essa chave em vez das credenciais OAuth da sua assinatura. Em modo não interativo com a flag -p, a chave é sempre usada quando presente. Consulte authentication precedence para a ordem de resolução completa. Para usar sua assinatura em vez disso, desdefina a variável de ambiente e remova-a do seu perfil de shell:

macOS/Linux
Windows PowerShell

unset ANTHROPIC_API_KEY
claude

Remove-Item Env:ANTHROPIC_API_KEY
claude

Verifique ~/.zshrc, ~/.bashrc ou ~/.profile para linhas export ANTHROPIC_API_KEY=... e remova-as para tornar a alteração permanente. No Windows, verifique seu perfil PowerShell em $PROFILE e suas variáveis de ambiente do usuário para ANTHROPIC_API_KEY. Execute /status dentro do Claude Code para confirmar qual método de autenticação está ativo. Quando Claude Code é executado em WSL2, em uma máquina remota via SSH ou dentro de um container, o navegador geralmente abre em um host diferente e seu redirecionamento não consegue alcançar o servidor de callback local do Claude Code. Depois que você faz login, o navegador mostra um código de login em vez de redirecionar automaticamente. Cole esse código no terminal no prompt Paste code here if prompted para completar o login. Se o navegador não abrir nada do WSL2, defina a variável de ambiente BROWSER para o caminho do seu navegador do Windows:

export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"
claude

Alternativamente, pressione c no prompt de login interativo para copiar a URL OAuth, ou copie a URL que claude auth login imprime, e abra-a em um navegador em sua máquina local. Se colar o código no prompt interativo não fizer nada, o atalho de cola do seu terminal provavelmente não está alcançando o campo de entrada. Tente o atalho de cola alternativo do seu terminal, frequentemente clique direito ou Shift+Insert no Windows Terminal, ou use claude auth login em vez disso, que lê o código colado da entrada padrão:

claude auth login

Este fallback também se aplica no Windows nativo ou qualquer terminal onde colar no prompt interativo falha.

Not logged in or token expired

Se Claude Code solicitar que você faça login novamente após uma sessão, seu token OAuth pode ter expirado. Execute /login para re-autenticar. Se isso acontecer frequentemente, verifique se seu relógio do sistema está preciso, pois a validação de token depende de timestamps corretos. Sessões paralelas em uma máquina compartilham um login salvo e coordenam sua renovação para que apenas um processo atualize o token por vez. Para saber o que as outras sessões fazem depois que você faz login novamente em uma delas, consulte Not logged in. Antes da v2.1.211, acordar a máquina do sono poderia fazer com que duas sessões renovassem com o mesmo token, o que revogava o login salvo e solicitava que cada sessão aberta fizesse login novamente de uma vez. No macOS, Claude Code salva credenciais no Keychain de login. Quando o Keychain rejeita a escrita, como quando está bloqueado em uma sessão SSH ou sua senha está fora de sincronização com sua senha de conta, Claude Code salva seu login no arquivo de texto simples ~/.claude/.credentials.json em vez disso. Um login do Console que cria uma chave de API falha até que o Keychain seja gravável novamente. Para tornar o Keychain gravável novamente e mover seu login de volta para o Keychain criptografado:

Verificar acesso ao Keychain

Execute claude doctor para verificar o acesso ao Keychain. Quando o Keychain rejeita gravações, o relatório lista um aviso que começa com macOS Keychain is not writable, seguido por uma correção sugerida. Quando o relatório não lista nenhum aviso do Keychain, o Keychain é gravável e você pode pular para a última etapa.

Desbloquear o Keychain

security unlock-keychain ~/Library/Keychains/login.keychain-db

Digite sua senha do Keychain quando o comando solicitar, depois execute claude doctor novamente. Quando o desbloqueio funcionou, o relatório não lista mais o aviso do Keychain.

Ressincronizar a senha do Keychain se desbloquear não ajudar

Abra Keychain Access, selecione o keychain login e escolha Edit > Change Password for Keychain “login” para ressincronizá-lo com sua senha de conta. Depois execute claude doctor novamente. Prossiga para a próxima etapa assim que o relatório não listar mais o aviso do Keychain.

Sair e fazer login novamente

Assim que o Keychain for gravável novamente, Claude Code move as credenciais de volta na próxima vez que grava uma credencial. Para forçar agora, execute /logout e depois /login. Sair remove todas as credenciais armazenadas, incluindo o conteúdo do arquivo de texto simples, logins de servidor MCP salvos e valores sensíveis de plugin, então espere re-autorizar servidores MCP e re-inserir segredos de plugin depois. Fazer login novamente armazena seu login no Keychain.

Bedrock, Agent Platform, or Foundry credentials not loading

Se você configurou Claude Code para usar um provedor de nuvem e vê Could not load credentials from any providers no Amazon Bedrock, Could not load the default credentials no Google Cloud’s Agent Platform, ou ChainedTokenCredential authentication failed no Microsoft Foundry, seu CLI do provedor de nuvem provavelmente não está autenticado no shell atual. Para Amazon Bedrock, confirme que suas credenciais AWS são válidas:

aws sts get-caller-identity

Para Google Cloud’s Agent Platform, confirme que ANTHROPIC_VERTEX_PROJECT_ID e CLOUD_ML_REGION estão definidos em seu shell, depois defina credenciais padrão de aplicativo:

gcloud auth application-default login

Para Microsoft Foundry, confirme que ANTHROPIC_FOUNDRY_API_KEY está definido, ou faça login com a CLI do Azure para que a cadeia de credenciais padrão possa encontrar sua conta:

az login

Se as credenciais funcionam em seu terminal mas não na extensão VS Code ou JetBrains, o processo IDE provavelmente não herdou seu ambiente de shell. Defina as variáveis de ambiente do provedor nas configurações do próprio IDE, ou inicie o IDE a partir de um terminal onde elas já estão exportadas. Consulte Amazon Bedrock, Google Cloud’s Agent Platform, ou Microsoft Foundry para configuração completa do provedor.

Still stuck

Se nenhum dos itens acima resolver seu problema:

Verifique o GitHub repository para problemas conhecidos, ou abra um novo com seu sistema operacional, o comando de instalação que você executou e a saída de erro completa
Se claude --version funciona mas algo mais está errado, execute claude doctor para um relatório de diagnóstico automatizado
Se você conseguir iniciar uma sessão, use /feedback dentro do Claude Code para relatar o problema
Se o problema for com sua conta em vez da instalação, como um loop de login, uma assinatura que não é reconhecida ou uma organização desabilitada, entre em contato com o suporte da Anthropic: faça login em claude.ai (Usuários do Console: platform.claude.com), clique em suas iniciais no canto inferior esquerdo e selecione Get help. Consulte How to get support para o fluxo completo.

​Encontre seu erro

​Execute verificações de diagnóstico

​Verifique a conectividade de rede

​Verifique seu PATH

​Verifique se há instalações conflitantes

​Verifique permissões de diretório

​Verifique se o binário funciona

​Problemas comuns de instalação

​Install script returns HTML instead of a shell script

​command not found: claude after installation

​permission denied when adding to your PATH

​curl: (56) Failure writing output to destination

​Homebrew cask unavailable or outdated

​Cask 'claude-code@latest' is not installed

​TLS or SSL connection errors

​Failed to fetch version from downloads.claude.ai

​The connection dropped while downloading the update

​Release verification failed for Claude Code

​Auto-update failed · Run claude doctor in the session footer

​Wrong install command on Windows

​running scripts is disabled on this system

​The process cannot access the file during Windows install

​claude.exe missing after an update on Windows

​Install killed on low-memory Linux servers

​Installation was killed before it could finish

​Install hangs in Docker

​Raw mode is not supported during install

​claude update or claude doctor hangs

​Claude Desktop overrides the claude command on Windows

​Claude Code on Windows requires either Git for Windows (for bash) or PowerShell

​Claude Code does not support 32-bit Windows

​Linux musl or glibc binary mismatch

​Illegal instruction

​dyld: cannot load on macOS

​Bus error while a session is running

​Exec format error on WSL1

​npm install errors in WSL

​Permission errors during installation

​Native binary not found after npm install

​npm ENOTEMPTY error during update or reinstall

​Login e autenticação

​Redefinir seu login

​OAuth error: Invalid code

​403 Forbidden after login

​Claude Code access has not been granted for this account

​This organization has been disabled with an active subscription

​OAuth login fails in WSL2, SSH, or containers

​Not logged in or token expired

​Bedrock, Agent Platform, or Foundry credentials not loading

​Still stuck

Encontre seu erro

Execute verificações de diagnóstico

Verifique a conectividade de rede

Verifique seu PATH

Verifique se há instalações conflitantes

Verifique permissões de diretório

Verifique se o binário funciona

Problemas comuns de instalação

Install script returns HTML instead of a shell script

`command not found: claude` after installation

`permission denied` when adding to your PATH

`curl: (56) Failure writing output to destination`

Homebrew cask unavailable or outdated

`Cask 'claude-code@latest' is not installed`

TLS or SSL connection errors

`Failed to fetch version from downloads.claude.ai`

The connection dropped while downloading the update

Release verification failed for Claude Code

`Auto-update failed · Run claude doctor` in the session footer

Wrong install command on Windows

`running scripts is disabled on this system`

`The process cannot access the file` during Windows install

`claude.exe` missing after an update on Windows

Install killed on low-memory Linux servers

Installation was killed before it could finish

Install hangs in Docker

`Raw mode is not supported` during install

`claude update` or `claude doctor` hangs

Claude Desktop overrides the `claude` command on Windows

Claude Code on Windows requires either Git for Windows (for bash) or PowerShell

Claude Code does not support 32-bit Windows

Linux musl or glibc binary mismatch

`Illegal instruction`

`dyld: cannot load` on macOS

`Bus error` while a session is running

`Exec format error` on WSL1

npm install errors in WSL

Permission errors during installation

Native binary not found after npm install

npm `ENOTEMPTY` error during update or reinstall

Login e autenticação

Redefinir seu login

OAuth error: Invalid code

403 Forbidden after login

Claude Code access has not been granted for this account

This organization has been disabled with an active subscription

OAuth login fails in WSL2, SSH, or containers

Not logged in or token expired

Bedrock, Agent Platform, or Foundry credentials not loading

Still stuck