Se você segue no coding com IA, com certeza vai encontrar erros. O momento em que o texto vermelho aparece e sua mão trava — esse tempo é o maior inimigo da produtividade. Mas fique tranquilo. Os erros com que você se depara no Claude Code e em outras ferramentas de coding com IA são, em sua maioria, a repetição de padrões definidos. Bastando distinguir o tipo, o tratamento se define de forma quase mecânica. Este capítulo é o mapa de triagem (classificação) de problemas que você abre primeiro quando trava.
Tornar-se alguém que "não trava por causa de erro"
🧭 Primeiro, um artigo de resumo. O apanhado geral que reúne de forma transversal os erros comuns é "Erros comuns do Claude Code e como resolver". Este capítulo é o mapa que dá a visão de cada categoria; os artigos individuais linkados trazem exemplos concretos de mensagem e os passos. Coloque nos favoritos e, ao travar, siga a partir daqui — é a recomendação.
Triar os erros por "tipo"
O primeiro passo do tratamento é distinguir "de que tipo é este erro". Se a camada da causa é diferente, o lugar de corrigir também é. Antes de ler a mensagem em detalhe, encaixe-a primeiro em uma das 6 categorias a seguir. No momento em que você encaixa, 80% do tratamento já está definido.
De cara não inicia / o comando não existe. Problema na porta de entrada. ↓ detalhes
Não loga / a autenticação cai. Conexão com a conta. ↓ detalhes
Não comunica / servidor sobrecarregado. Problema no caminho e do lado do servidor. ↓ detalhes
Atingiu o teto / período em que não dá para usar. Problema de plano e consumo. ↓ detalhes
Longo demais / abarrotado demais. Problema da quantidade de informação entregue. ↓ detalhes
A extensão / chamada de ferramenta falha. Problema das funções periféricas. ↓ detalhes
💡 Dica para distinguir. Uma única palavra-chave dentro do texto do erro já dá o palpite. command not found → ①, authentication / login → ②, connection / network / 529 → ③, usage limit → ④, too long → ⑤, MCP / tool → ⑥. Antes de ler a mensagem inteira, procure primeiro por essa palavra.
① Instalação/execução — comando não encontrado
O primeiro obstáculo é "simplesmente não inicia". A instalação falhou no meio, ou o PATH não está configurado, e nada responde por mais que você digite o comando. Travar aqui impede seguir adiante, então confira a porta de entrada com calma.
Sintoma: ao digitar claude, retorna "esse comando não existe".
Causa: o PATH não aponta para o local da instalação, o shell não foi recarregado, ou a própria instalação não se concluiu.
Tratamento: reabrir o terminal / conferir o PATH / reinstalar. Testando em ordem, na maioria das vezes você escapa.
Sintoma: para com erro durante a instalação / é rejeitado por permissão.
Causa: versão do Node.js antiga, permissão insuficiente, falha ao obter o pacote pela rede.
Tratamento: atualize o ambiente base (Node etc.) e reveja permissões de administrador e o método de instalação. Em rede corporativa, suspeite também do proxy.
🔧 Os passos detalhados aqui. A triagem de causa e as correções concretas de falha na instalação e de command not found estão reunidas em "como corrigir command not found / erro de instalação". Travou na instalação? O caminho mais curto é reinstalar seguindo os passos do Capítulo 2 "Começar com o Claude Code".
② Login/autenticação — a autenticação não passa
É o padrão em que inicia, mas é rejeitado no login ou na autenticação. Aparece de formas como a autenticação pelo navegador não dar certo, ou ser deslogado de repente depois de um tempo usando. É o estado em que o "aperto de mãos" entre a conta e a ferramenta está desalinhado.
Sintoma: não avança da tela de login / é rejeitado por erro de autenticação / o navegador de autenticação não abre.
Causa: token de autenticação expirado/corrompido, falha no redirecionamento, engano de plano ou de conta-alvo, relógio dessincronizado.
Tratamento: deslogar e logar de novo / limpar as credenciais salvas e reautenticar / conferir se é a conta certa.
O que parece "erro de autenticação" às vezes é, na verdade, só um plano ou contrato de alvo diferente.
Quem usa várias contas em alternância, confira primeiro a conta logada e o tipo de plano. Misturar a conta corporativa com a pessoal é uma armadilha típica.
🔑 Os passos detalhados aqui. Os passos de relogin e de reobtenção de token quando a autenticação não passa estão em "como resolver erros de login / autenticação". A maioria se resolve com um novo sign in, mas, se não corrigir, suspeite também do lado da rede (③).
③ Conexão/rede — não conecta / sobrecarga
Aqui a causa se divide em 2, "do seu lado" e "do lado do servidor", então a triagem é crucial. É a sua conexão ou o proxy que estão bloqueando, ou o servidor que está temporariamente congestionado? No primeiro caso, você mesmo corrige; no segundo, a política básica é esperar ou aliviar.
Sintoma: não conecta / dá timeout / a comunicação cai no meio.
Causa: instabilidade da conexão, bloqueio por proxy ou firewall corporativo, VPN, problema de certificado ou DNS.
Tratamento: testar em outra conexão / desligar a VPN / rever as configurações de proxy. Em rede corporativa, confirme com o administrador os alvos permitidos.
Sintoma: retorna overloaded ou 5xx. Falha mesmo com a sua configuração correta.
Causa: alta carga ou falha temporária do lado do servidor. Não é culpa do seu código ou configuração.
Tratamento: esperar um pouco e tentar de novo / evitar horários de pico / conferir informações de incidente (página de status).
⚠️ Referência de triagem. Se outros sites e serviços estão normais e só a ferramenta de IA cai, é alta a chance de ser do lado do servidor (529/500), e o tratamento é "esperar". Se as outras conexões também estão instáveis, é do seu lado (conexão, proxy, VPN). Para detalhes, veja "erros de conexão / rede / proxy" e "o significado e o tratamento do erro 529 overloaded / 500".
④ Limite de uso — atingiu o teto
Não é um erro, e sim um aviso de "como você atingiu o limite, agora não dá para usar". Cada plano tem um teto de consumo por certo intervalo de tempo e por semana; ao encostar nele, para temporariamente. Como não é defeito, o certo não é tentar consertar, e sim ajustar pelo uso e pelo plano.
Sintoma: aparece "limite de uso atingido" e fica indisponível até certo horário.
Causa: chegou ao teto de consumo do plano. Rodar tarefas grandes ou conversas longas em pouco tempo faz chegar mais rápido.
Tratamento: esperar o reset / dividir a conversa e usar de leve / se preciso, rever o plano.
Sintoma: atinge o teto no meio da semana / a hora do reset parece mais cedo ou mais tarde do que você achava.
Causa: a cota semanal às vezes segue um mecanismo que conta a partir do primeiro uso, e não necessariamente a semana do calendário.
Tratamento: entenda corretamente como o reset é contado e distribua com planejamento os trabalhos de alto consumo.
📊 O teto é quase evitável com "gestão". O significado do teto e como pensar o tempo de espera estão em "tratamento ao atingir o limite de uso"; como o reset semanal é contado, em "o mecanismo do reset antecipado do limite semanal". Um uso que evita encostar no teto é tratado em conjunto no Capítulo 7 "Custo e eficiência".
⑤ Entrada/contexto — longo demais
A quantidade de informação (contexto) que a IA consegue tratar de uma vez tem um teto. Se a conversa se estende, ou se você entrega um arquivo gigante por inteiro, ela recusa com "a entrada é longa demais". Isso é um sinal de abarrotamento, então o tratamento é reduzir a quantidade entregue ou dividi-la.
Sintoma: aparece "a entrada é longa demais" e a instrução não é executada.
Causa: acúmulo do histórico da conversa, leitura de arquivos gigantes ou de muitos arquivos, log colado longo demais.
Tratamento: organizar/resumir a conversa / iniciar uma nova conversa / entregar só o trecho necessário / dividir a tarefa em partes pequenas.
Sintoma: ocorre erro no processamento em torno do raciocínio (thinking) e a resposta é interrompida.
Causa: inconsistência do estado da conversa ou um descompasso interno envolvendo o histórico. Ocorre mais em conversas longas.
Tratamento: começar uma nova conversa / separar a troca em questão. A maioria se resolve com um refresh.
✂️ "Longo" se previne pelo desenho. As formas concretas de reduzir estão em "como resolver prompt is too long"; os problemas em torno do thinking, em "tratamento do erro de thinking block". A solução de raiz é dividir a tarefa em partes pequenas, o que se liga diretamente ao jeito de dar instrução tratado no Capítulo 4 "Pedir bem".
⑥ MCP/ferramentas — a extensão não funciona bem
Com MCP (integração de ferramentas externas) e chamadas de ferramenta, às vezes o próprio Claude Code está normal e só a extensão periférica falha. A dica é pensar separando do erro do próprio corpo. Verificar primeiro "reproduz mesmo sem a extensão?" faz a triagem da causa avançar de uma vez.
Sintoma: não conecta ao servidor MCP / a ferramenta integrada não aparece na lista ou não reage.
Causa: erro na escrita do arquivo de configuração, falha ao iniciar o servidor, PATH ou dependências ausentes, credenciais inadequadas.
Tratamento: revisar a configuração / confirmar que o servidor inicia sozinho / removê-lo uma vez e triar se o corpo funciona só.
Sintoma: a chamada da ferramenta falha / trava na entrega do resultado da chamada.
Causa: inconsistência na definição ou nos argumentos da ferramenta, desalinhamento do estado da conversa, instabilidade temporária do destino integrado.
Tratamento: recomeçar a conversa / desativar temporariamente a ferramenta em questão para triar / conferir o estado do destino integrado.
Sintoma: dá erro no status check em torno do PR (pull request).
Causa: costuma envolver a configuração ou permissão do CI/check integrado e o estado do serviço externo.
Tratamento: conferir a configuração/permissão do lado do check / reexecutar / conferir o estado do serviço externo.
🧩 A série de extensões, "remova e trie". Como corrigir a conexão MCP está em "tratamento do erro de conexão de MCP server"; os problemas de chamada de ferramenta, em "tratamento do erro de chamada de ferramenta"; o relacionado a check de PR, em "tratamento do erro de status check de PR". O uso das próprias extensões é tratado no Capítulo 6 "Usar extensões".
Como escapar de um travamento — os 5 movimentos coringa
Mesmo quando você não identifica a causa na hora, há "movimentos coringa" que vale testar primeiro. Muitos erros somem apenas com um refresh do estado ou com o alívio da carga. Quando as categorias acima não derem palpite, teste estes 5 de cima para baixo.
Feche a ferramenta e o terminal e reabra. Distúrbios temporários de estado somem, na maior parte, só com isto. O primeiro movimento a suspeitar.
Conversas longas são um ninho de inconsistências. Inicie uma nova conversa ou resuma/organize o histórico (na lógica do /compact) para ficar leve. Bom para ⑤.
Não peça grande de uma vez; quebre a tarefa em pequenos passos. Erros de origem "longo demais / pesado demais" são evitados pela raiz assim.
529/500 e congestionamento o tempo resolve. Espere alguns minutos e reexecute. Confira também incidentes na página de status. Bom para ③④.
Se realmente não descobrir, entregue o texto do erro inteiro à IA ou à busca. Confrontando com o artigo de resumo deste capítulo, quase sempre cai num padrão conhecido.
🧯 Não se afobar é o maior tratamento. O erro não é sinal de "quebrou", e sim uma dica de "conserte aqui". Distinga a categoria, teste os 5 movimentos acima e, se ainda assim não der, vá ao artigo individual. Basta dominar esse fluxo para que o texto vermelho deixe de assustar.
- Primeiro, trie o erro em 6 categorias (instalação, autenticação, conexão, limite de uso, contexto, MCP/ferramentas). Uma palavra-chave já dá o palpite.
- Cada categoria tem sintoma → causa → tratamento quase fixos. O lado do servidor (529/500) é "esperar"; longo demais é "dividir / organizar".
- Mesmo sem saber a causa, os 5 movimentos coringa (reiniciar, recomeçar a conversa, dividir em partes, esperar e tentar de novo, entregar o texto do erro tal e qual) resolvem a maioria.
- Os passos concretos estão no artigo de resumo e em cada artigo individual. A gestão de teto no Capítulo 7, as extensões no Capítulo 6.
Entendido o jeito de conviver com os erros, o coding com IA avança de uma vez. Agora é a vez de ampliar a própria capacidade do Claude Code. No próximo Capítulo 6 "Usar extensões", vamos deixar o parceiro ainda mais forte com hooks, plugins, subagents e MCP.