Erros do Claude Code: 5 problemas comuns e como resolver rápido (2026)

O Claude Code lança atualizações rápido, então nomes de comandos e comportamento podem mudar; vou sinalizar tudo o que você deve conferir por conta própria. Cruze as informações com a documentação oficial do Claude Code quando precisar de certeza.

Consulta rápida de erros (sintoma → correção)

Esta é a principal seção de referência. Encontre a linha que combina com a mensagem que você está vendo, siga a última coluna e pule para a seção detalhada se quiser entender a causa.

Antes de consertar qualquer coisa: problema seu ou da Anthropic?

O erro mais comum de quem está começando é partir direto para reinstalar e reescrever config quando o problema, na verdade, mora no servidor. Antes de cada correção, gaste 30 segundos para classificar:

• Do seu lado (ambiente/config): command not found, um PATH errado, autenticação quebrada, um bloqueio de permissão, um contexto cheio. Sinal claro: se repete de forma consistente, a mesma mensagem toda vez.
• Do lado da Anthropic (você não consegue resolver): uma mensagem overloaded, o modelo não respondendo mesmo com a sua rede boa, um erro que aparece do nada quando você não mudou nada. Sinal claro: é repentino e costuma se resolver sozinho em alguns minutos.

Três comandos para triar rápido: claude --version (instalou certo?) → /status (em qual rota estou, ainda tenho cota?) → abra a página oficial de status da Anthropic (algum incidente no sistema?). Se os três estiverem ok e você ainda estiver travado, então é hora de arrumar o seu ambiente local.

Erro 1 - Instalado, mas o claude não roda (command not found / PATH)

Sintoma. Você terminou de instalar, mas digitar claude te dá uma destas mensagens:

# macOS / Linux (zsh, bash)
zsh: command not found: claude

# Windows (PowerShell / CMD)
claude : The term 'claude' is not recognized as the name of a cmdlet...

A parte frustrante: o npm informa que a instalação deu certo, mas o terminal ainda não acha o comando.

Causa. O pacote foi parar na pasta global bin do npm, mas essa pasta não está na sua variável de ambiente PATH, então o shell não faz ideia de onde encontrar o binário do claude. No Windows, uma variável de ambiente que você define em uma janela geralmente some no instante em que você abre outra.

Correção. Primeiro, encontre a pasta global bin do npm:

npm config get prefix
# e.g. returns: /Users/you/.npm-global (macOS)
# or: C:\Users\you\AppData\Roaming\npm (Windows)

O comando fica em PREFIX/bin (macOS/Linux) ou no próprio PREFIX (Windows). Adicione-o ao seu PATH:

# macOS / Linux - append to the end of ~/.zshrc (or ~/.bashrc)
export PATH="$(npm config get prefix)/bin:$PATH"
# then reload
source ~/.zshrc

# verify
claude --version

No Windows, abra o seu perfil do PowerShell e adicione a linha equivalente, ou adicione o caminho do npm à variável PATH do sistema (Configurações → Variáveis de Ambiente) e então reabra o terminal. Mas aqui vai a minha recomendação prática: no Windows, rode o Claude Code dentro do WSL2 em vez do PowerShell/CMD nativo - o ambiente Linux contorna quase todos os problemas chatos de PATH e permissão específicos do Windows.

Se ainda não for reconhecido depois de arrumar o PATH, o mais provável é que a instalação original não tenha ficado limpa. Volte em como instalar o Claude Code do jeito certo e recomece do zero.

Erro 2 - Não consegue logar / falhas de autenticação (chave de API vs assinatura)

Sintoma. O login trava no navegador, diz unauthorized, ou o Claude Code fica exigindo uma chave de API mesmo você achando que já entrou com um plano Pro/Max.

Causa. Duas origens costumam causar dor de cabeça aqui. Uma é um cache de credenciais corrompido - um token antigo entalado. A segunda, e mais comum, é a confusão entre duas rotas de autenticação: entrar com uma assinatura (um plano Pro/Max via sua conta) é completamente diferente de usar ANTHROPIC_API_KEY (cobrado por token). Se você algum dia definiu a variável de ambiente ANTHROPIC_API_KEY, o Claude Code pode preferir a rota da chave de API e ignorar o plano que você paga.

Correção. Primeiro, redefina suas credenciais:

claude logout
claude login # sign in again on the route you want (subscription)

Depois, verifique se uma variável de chave de API está 'furando a fila':

# macOS / Linux
echo $ANTHROPIC_API_KEY

# Windows (PowerShell)
echo $env:ANTHROPIC_API_KEY

Se você quer usar o seu plano Pro/Max mas essa variável tem um valor, remova-a do seu perfil de shell (a linha export ANTHROPIC_API_KEY=... no .zshrc, ou a variável de ambiente no Windows) e reabra o terminal. Por fim, rode /status dentro do Claude Code para confirmar que está na rota certa. Por outro lado, se você quer de propósito usar uma chave de API, garanta que ela ainda é válida e tem crédito.

Erro 3 - 'Rate limit reached' / erro 429

Sintoma. Você está seguindo o trabalho e ele para no meio da tarefa com uma mensagem Rate limit reached ou um código 429, às vezes até quando você mal usou.

Causa. A armadilha é que dois sistemas diferentes mostram a mesma linha, mas a forma de lidar com cada um é oposta:

Correção. Primeiro identifique sua rota com /status. Depois cace processos órfãos - o Claude Code às vezes deixa um processo rodando em segundo plano depois que você fecha a janela, e ele continua contando contra a sua cota:

# macOS / Linux - list live claude processes
ps aux | grep claude
# see a stray PID? kill it: kill <PID>

# Windows: open Task Manager, find lingering node/claude processes and end them

Se a sua rota é um plano de assinatura e você realmente esgotou, não há truque além de esperar a janela resetar ou trocar temporariamente para um modelo mais leve para economizar uso. Com uma chave de API, aumentar o limite é questão do tier da sua conta. Para saber exatamente de qual regra veio um 429 específico, cruze as informações com as issues do repositório anthropics/claude-code.

Erro 4 - O Claude Code trava / empaca no meio da tarefa (contexto cheio)

Sintoma. A sessão congela, as respostas ficam lentíssimas, o modelo começa a 'esquecer' o que você disse no início, ou entra num loop sem fim de editar e reeditar que nunca termina.

Causa. Geralmente é uma janela de contexto cheia: você teve uma conversa muito longa, colou um arquivo enorme ou passou uma tarefa tão grande que a saída explode. Isso não é um erro de servidor - então não confunda com uma mensagem overloaded do lado da Anthropic.

Correção. Do mais leve ao mais pesado:

• /compact - comprime a conversa, mantendo os pontos-chave mas liberando espaço. Use quando você ainda quer continuar a linha de trabalho atual.
• /clear - apaga o contexto e começa do zero. Use quando você está indo para uma tarefa sem relação.
• Divida a tarefa em partes sequenciais. Em vez de 'refatore o módulo inteiro', passe um arquivo de cada vez. Aqui, prevenir é melhor que remediar.
• Evite colar um arquivo gigante inteiro no chat - deixe o Claude Code ler o arquivo sozinho quando precisar, em vez de enfiar tudo no contexto.
• Se estiver totalmente congelado: saia da sessão (Ctrl+C) e reabra. Você perde o contexto atual, mas encerra de vez o estado travado.

Se você quer se aprofundar em gerenciar o contexto para evitar travamentos, o fluxo metódico e amigável para iniciantes em 10 passos para começar com o Claude Code vai te ajudar a repassar o trabalho de forma limpa desde o início.

Erro 5 - Bloqueado por permissões (não consegue rodar um comando)

Sintoma. O Claude Code pede confirmação antes de todo comando, ou simplesmente se recusa a rodar um comando / editar um arquivo, interrompendo o seu fluxo.

Causa. Isso geralmente não é um 'bug' - é um recurso de segurança: o modo de permissão está bloqueando uma operação arriscada até você conceder acesso. Por padrão, o Claude Code é cauteloso com comandos que podem modificar/apagar arquivos ou rodar um shell.

Correção. Conceda acesso de forma controlada:

• Quando o Claude Code perguntar, escolha acesso por sessão para operações em que você confia, em vez de clicar em aprovar toda santa vez.
• Adicione os comandos que você mais usa a uma allowlist para ele parar de perguntar.
• Entenda os diferentes modos de permissão para poder escolher o nível que combina com o que você está fazendo.

Um aviso honesto: não ligue o modo que pula todas as confirmações só para 'ir mais rápido'. Ele deixa o Claude Code rodar qualquer comando sem perguntar - conveniente, mas um risco real se o modelo fizer algo que você não previu numa máquina ou repositório importante. Use só num ambiente isolado (um sandbox/contêiner).

Configurar permissões com segurança tem várias camadas, então vou desdobrar isso num guia dedicado e aprofundado sobre permissões e modos de permissão do Claude Code que você configura uma vez e usa com confiança por muito tempo.

Ainda pegando errinhos? Checklist e quando reinstalar

Se você passou por todos os 5 grupos acima e ainda pega errinhos estranhos, rode este checklist inteiro antes mesmo de pensar em reinstalar:

• Atualize para o build mais recente: npm i -g @anthropic-ai/claude-code - muitos bugs são corrigidos em releases posteriores.
• Confira se o Node está numa versão LTS (alguns erros desconcertantes vêm de o Node estar velho ou novo demais).
• Mantenha um terminal rodando o Claude Code por projeto para evitar conflitos e processos órfãos.
• Limpe o cache de credenciais com claude logout e entre de novo.
• Reinstalação limpa: desinstale totalmente e reinstale seguindo o guia de instalação do Claude Code.
• Não tem certeza de como a ferramenta funciona de verdade? Releia o que é o Claude Code para ganhar o modelo mental certo - muitos 'erros' são, na real, mal-entendidos de como ela opera.

Quando falar com o suporte da Anthropic: um erro que persiste mesmo numa máquina limpa, mensagens overloaded repetidas por horas, ou um problema de cobrança/conta que você não consegue ajustar sozinho.

Menos erros e mais poder com um kit pronto (AgentKit)

Boa parte dos errinhos vem de o ambiente de cada máquina ser diferente: um PATH torto, config espalhada, skills padrão ou uma statusline faltando. Se você prefere parar de brigar com configuração manual, o kit AgentKit para o Claude Code traz config, skills e até um construtor de statusline prontos, que ajudam a padronizar o seu ambiente de trabalho - evitando boa parte dos erros chatos de config e mantendo as sessões mais estáveis. Ele não 'conserta' os erros de CLI acima por você, mas reduz as chances de eles aparecerem já de cara. Se quiser experimentar, você pode dar uma chance ao AgentKit (20% de desconto pelo link) e ver se o setup pronto combina com o seu jeito de trabalhar.

Perguntas frequentes (FAQ)

Por que digitar claude retorna command not found?

Porque a pasta que guarda o comando (o global bin do npm) não está na sua variável de ambiente PATH, então o shell não acha o binário. Rode npm config get prefix, adicione a pasta /bin correspondente ao PATH e reabra o terminal.

O Claude Code roda no Windows / PowerShell?

Roda, mas a experiência é bem mais tranquila com o WSL2 do que com o PowerShell/CMD nativo. O WSL2 evita a maioria dos problemas de PATH e permissão específicos do Windows.

Quanto tempo dura o 'Rate limit reached'?

Depende da origem. Se for cota do plano Pro/Max, você tem que esperar a janela de tempo resetar. Se for o limite de RPM/TPM de uma chave de API, reduzir as suas requisições simultâneas resolve na hora. Rode /status para ver em qual você bateu.

O que eu faço quando o Claude Code trava?

Geralmente é contexto cheio. Use /compact para comprimir a conversa ou /clear para resetar, divida a tarefa em partes menores e evite colar arquivos gigantes. Se estiver totalmente congelado, saia da sessão (Ctrl+C) e reabra.

Um erro de login é causado pela chave de API ou pelo plano?

Confira a variável ANTHROPIC_API_KEY: se ela tem um valor, o Claude Code pode pegar a rota da chave de API em vez do plano que você pagou. Para usar o seu plano Pro/Max, remova essa variável e depois rode claude logout e claude login de novo.

Como eu reinstalo o Claude Code?

Desinstale o pacote antigo, rode npm i -g @anthropic-ai/claude-code de novo, garanta que o Node está numa versão LTS e confirme que a pasta global bin do npm está no seu PATH. Depois rode claude login do zero.

Conclusão + próximos passos

Resumo da ópera: não conserte no chute. Classifique primeiro - problema seu ou da Anthropic - e então conserte pelo grupo de sintoma correspondente: não roda/PATH, autenticação, limite de uso, travamento/contexto ou permissão. Os três comandos claude --version, /status e /compact resolvem a maioria das situações do dia a dia. Se você está batendo em erros logo na instalação, volte ao guia de instalação do Claude Code; e se você está só começando e quer evitar erros na raiz, siga os 10 passos para iniciantes. Para padronizar o seu ambiente e reduzir os errinhos no longo prazo, dê uma olhada na review do AgentKit para o Claude Code.