Solução de Problemas Comuns (FAQ / Troubleshooting)
📚 Navegação da Série: O artigo anterior 50 Antipadrões: Erros de Uso Comuns apontou um a um os hábitos que parecem corretos mas que trazem problemas. Este artigo foca na solução de problemas — quando o Claude Code apresentar falhas, mostraremos como investigá-las sistematicamente até a causa raiz. Erros de instalação, falhas de login, bloqueios de permissão, desconexão de MCP, lentidão ou mensagens de erro vermelhas no terminal... Este texto fornece um guia prático com base em "sintoma → onde consultar e o que executar".
Apresentamos inicialmente um cenário muito típico e fácil de induzir a erro, cuja compreensão esclarece o objetivo deste artigo.
Imagine o seguinte cenário: você acabou de migrar para um novo Mac, instalou o Claude Code a partir de um projeto da empresa e, logo ao iniciar, recebe a mensagem This organization has been disabled. A primeira reação costuma ser "pronto, minha conta foi banida", e você corre no claude.ai para checar a assinatura — tudo certo, o plano Max está ativo. Depois, desconfia da conexão, ativa uma VPN e tenta de novo, mas a mesma mensagem persiste. Após insistir por quase quarenta minutos, reinstalar o Claude Code duas vezes e quase abrir um chamado de suporte...
Qual era a causa raiz? Ao migrar as configurações del Mac antigo, o arquivo ~/.zshrc continha a linha export ANTHROPIC_API_KEY=... que já havia sido esquecida, remanescente de uma chave antiga de um projeto de empresa encerrado há seis meses. A prioridade das variáveis de ambiente se sobrepôs ao login de assinatura, e o Claude Code tentou autenticar usando a chave inativa, resultando no alerta de organização desabilitada. Executar apenas unset ANTHROPIC_API_KEY resolveu o problema instantaneamente.
O objetivo desse exemplo é fixar uma regra: evite tentar "adivinhar" o problema ao fazer diagnósticos. Aqueles quarenta minutos foram perdidos em suposições — sobre a conta, sobre a rede, e quanto mais se supunha, mais longe da solução se ficava. O Claude Code já traz ferramentas de diagnóstico integradas; o comando /status informa de forma clara "qual conjunto de credenciais está em uso", poupando suposições. Este artigo ensina como encurralar o problema de forma metodológica, sem adivinhações.
Ao terminar de ler este artigo, você terá:
- Uma tabela geral de direcionamento "sintoma → onde consultar": identifique o erro primeiro, evitando testes aleatórios
- Conhecimento sobre os dois principais comandos de autoajuda —
/doctorpara diagnóstico e/feedbackpara reportar falhas — e quando utilizá-los - Resoluções mapeadas para seis categorias principais (instalação, login/autenticação, permissões, MCP, desempenho e mensagens de erro)
- Como usar os parâmetros de depuração
--debuge o método de comparação com configurações limpas, que é uma técnica altamente eficaz - Um exercício prático guiado com saídas esperadas: rodar o
/doctorpara validar a sua própria instalação
01 Princípio Fundamental de Diagnóstico: Classifique o problema primeiro, evite testes aleatórios
Direto ao ponto: este princípio é mais importante do que qualquer comando específico — diante de um erro, o primeiro passo não é tentar corrigi-lo, mas classificar em qual categoria ele se enquadra — se é de instalação, de login, de configuração ou da própria API. Se errar a classificação, os passos seguintes serão em vão.
Analogia: fechar o registro em um vazamento antes de quebrar o piso. Se há uma infiltração em casa, um profissional experiente não começará quebrando paredes — ele avaliará se o problema é na torneira, em uma conexão ou se vem do andar de cima. Se errar o diagnóstico, quebrará o piso à toa sem achar o vazamento. O diagnóstico do Claude Code segue a mesma lógica: classifique primeiro, aja depois.
Por que isso é tão importante? Porque a documentação oficial do Claude Code já é estruturada por categorias — uma página para instalação e login, outra para erros em tempo de execução, outra para configurações e depuração, e outra para desempenho. Se você não souber a categoria do problema, não saberá qual seção consultar. A documentação oficial inicia com uma tabela de direcionamento, que adaptamos para as situações mais comuns:
| Sintoma observado | Categoria correspondente / Onde consultar |
|---|---|
command not found: claude, falha na instalação, problema com PATH, EACCES | Instalação (veja o Artigo 02 e a Seção 02 deste artigo) |
Solicitação recorrente de login, 403 Forbidden, organization disabled | Login e Autenticação (Seção 03 deste artigo) |
| Ajuste não aplicado, hooks não acionados, MCP server não carregado, regras de permissão ineficazes | Configuração (Seção 04 deste artigo e Depuração de Configurações) |
API Error: 5xx, 529 Overloaded, 429 | Erros de API (Seção 06 deste artigo, geralmente temporários do servidor) |
model not found / you may not have access to it | Erros de Modelo (Seção 06 deste artigo, modelo incorreto ou sem acesso) |
| Lentidão, alto uso de CPU/memória, busca não encontra arquivos | Desempenho (Seção 05 deste artigo) |
O uso é simples: identifique na coluna da esquerda a frase mais parecida com a que aparece na sua tela, e la coluna da direita indicará a direção do diagnóstico. As seções seguintes detalham cada uma dessas categorias.
Vale destacar uma recomendação oficial importante: "Se você não tiver certeza de qual categoria se aplica, execute
/doctorno Claude Code para verificar de forma automatizada a sua instalação, configurações, servidores MCP e uso do contexto. Se oclaudenão iniciar de forma alguma, executeclaude doctora partir do terminal."
Ou seja — está em dúvida sobre a categoria? Não se preocupe, rode o /doctor primeiro, pois ele apontará o caminho correto na maioria dos casos. A próxima seção detalha esses dois comandos utilitários.
💡 Resumo em uma frase: O primeiro passo do diagnóstico é sempre classificar o erro e evitar tentativas aleatórias — identifique a categoria na tabela de sintomas e vá para a seção correspondente; na dúvida, rode
/doctor.
02 Dois Comandos Utilitários: /doctor para Diagnóstico e /feedback para Envio de Relatórios
Antes de consultar qualquer manual ou fórum, o Claude Code oferece dois canais internos de suporte. Noventa por cento das falhas são apontadas diretamente pelo /doctor ou podem ser reportadas usando /feedback. Dominar esses dois comandos poupará bastante tempo.
Analogia: fazer exames antes de uma intervenção cirúrgica. Ao sentir um mal-estar, você não passa por uma cirurgia de imediato; faz uma bateria de exames primeiro — pressão arterial, batimentos cardíacos e exames laboratoriais ajudam o médico a identificar o problema. O /doctor funciona como o equipamento de exames do Claude Code: com um único comando, ele checa o status da instalação, a sintaxe das configurações, as conexões MCP e o espaço ocupado do contexto.
/doctor: Diagnóstico Completo
O /doctor deve ser sua primeira opção ao investigar falhas. Ele audita os seguintes pontos: status de integridade da instalação, validade das configurações (chaves inválidas ou erros de esquema), configurações MCP e consumo da janela de contexto.
O método depende se a aplicação inicia ou não:
- Se conseguir iniciar a sessão: Digite diretamente
/doctorna conversa com o Claude. - Se o
claudenão iniciar (como no errocommand not foundou falhas na inicialização): Digiteclaude doctordiretamente no terminal — note que este comando não tem barra, pois é um subcomando direto da CLI.
O /doctor possui um recurso conveniente: quando ele detecta um problema, você pode pressionar f para enviar o relatório de diagnóstico diretamente ao Claude, permitindo que ele guie você na correção. É como ter o médico ao lado explicando o resultado do exame.
/feedback: Envio de Relatórios
Se você consultou a documentação, rodou o /doctor e o erro persistir — não perca tempo tentando resolver sozinho, use o /feedback para reportar à Anthropic. Ele enviará seu histórico de conversa junto com a sua descrição do ocorrido, sendo esta a forma mais rápida de diagnosticar falhas subjetivas (como queda na qualidade das respostas sem mensagens de erro). O comando também oferece a opção de abrir uma issue no GitHub pré-preenchida com os dados do erro. Observação: se estiver utilizando provedores de nuvem como Bedrock ou Vertex, o /feedback não enviará dados à Anthropic, salvando apenas um arquivo local que deverá ser repassado ao seu representante de conta.
Talvez você conheça o termo
/bug— ele era o nome antigo desse processo de reporte. Atualmente, a documentação oficial unificou o termo em/feedback: ele envia os logs e a descrição do problema para a Anthropic na própria sessão, ou facilita a abertura de uma issue no GitHub. Basta lembrar do/feedback.
Tabela comparativa de comandos rápidos:
| Situação | Comando recomendado | Finalidade |
|---|---|---|
| Incerteza sobre a categoria do problema | /doctor | Diagnóstico completo instantâneo para indicar o rumo |
O claude não inicia no terminal | claude doctor (no terminal) | Diagnóstico executado antes de carregar a CLI |
O /doctor detectou problemas e você quer ajuda do Claude | Pressione f no resultado do /doctor | Encaminha o relatório de erro ao próprio Claude |
| Documentação e diagnóstico não resolveram | /feedback | Envia o log e descrição para a Anthropic |
| Suspeita de instabilidade geral nos servidores | Acessar status.claude.com no navegador | Verifica falhas de infraestrutura globais na API |
O link status.claude.com é especialmente útil: diante de erros como 5xx ou 529, a primeira ação deve ser verificar a página de status dos servidores, e não alterar suas configurações — na maioria das vezes, trata-se de instabilidade na infraestrutura da Anthropic, sem relação com suas configurações locais. Detalharemos isso na Seção 06.
💡 Resumo em uma frase: Comece a investigação com as ferramentas internas —
/doctor(ouclaude doctorno terminal) para diagnóstico,/feedbackpara reportar falhas complexas; em caso de falha de conexão com servidores, consultestatus.claude.com.
03 Login e Autenticação: Pedidos recorrentes de login ou organizações desabilitadas
A partir daqui, abordaremos as categorias de erros de forma pontual. Primeiramente, as falhas de login e autenticação — esses erros costumam preocupar iniciantes devido aos termos chamativos (disabled, Forbidden, revoked), mas as causas costumam ser bastante simples.
Analogia: crachá de acesso corporativo bloqueado. Se o crachá falhar no acesso físico, não significa demissão. Pode ser desmagnetização, uso do crachá antigo ou desalinhamento do relógio do leitor. Receber "acesso negado" não significa "falta de permissão permanente". Em autenticação ocorre o mesmo — valide primeiro "quais credenciais o Claude Code está enviando", evitando premissas catastróficas.
Passo 1: Identifique a credencial ativa
Este é o passo padrão em diagnósticos de acesso, que evita o desperdício de tempo. Digite na sessão:
/statusSaída esperada: Será exibido o método de validação ativo — se por assinatura (login via OAuth) ou por uma chave API. Se você possui um plano pago ativo, mas a saída exibe o uso de uma API key, a causa do problema está identificada.
O erro mais comum: ANTHROPIC_API_KEY sobrepondo a assinatura
Este é o cenário citado na introdução. A documentação oficial detalha a precedência de autenticação:
As variáveis de ambiente têm precedência sobre o
/login. Portanto, uma chave exportada nos arquivos de perfil do terminal ou carregada de arquivos.envserá utilizada, mesmo que você possua um plano Pro ou Max ativo. Em modos não interativos (-p), a chave será sempre utilizada quando configurada.
Dessa forma, caso exista uma chave ANTHROPIC_API_KEY no ambiente (mesmo que esquecida de projetos passados), o Claude Code a adotará para autenticação. Se ela estiver expirada ou pertencer a uma organização desativada, ocorrerá a falha This organization has been disabled. A solução:
unset ANTHROPIC_API_KEY
claudeA execução do unset afeta somente a janela ativa do terminal. Para correção permanente, acesse o arquivo ~/.zshrc, ~/.bashrc ou ~/.profile e delete a linha export ANTHROPIC_API_KEY=... (no Windows, verifique as variáveis de ambiente e o arquivo de configuração do PowerShell $PROFILE). Salve as alterações, reinicie o claude e valide o retorno via /status. Essa ordem de prioridade de credenciais foi abordada no Artigo 04 (Configurações de API) e vale como consulta rápida.
Resoluções para mensagens comuns de autenticação:
| Mensagem de erro típica | Causa provável | Solução recomendada |
|---|---|---|
Not logged in · Please run /login | Sessão sem credencial ativa | Execute /login; caso utilize variáveis de ambiente, valide se a chave ANTHROPIC_API_KEY foi exportada corretamente |
OAuth token revoked / has expired | Token de login inativo | Rode /login; se o erro persistir na mesma sessão, execute /logout antes de refazer o /login |
| Pedidos de login repetitivos em inicializações | Token expira continuamente | Valide o relógio do sistema operacional (a verificação do token exige sincronização de horário); no macOS, o Keychain bloqueado gera esse comportamento. Rode claude doctor para validar o acesso ao Keychain |
403 Forbidden (após o login) | Permissão de plano ou perfil insuficiente | Planos Pro/Max devem validar o status em claude.ai/settings; perfis no Console exigem a permissão de Claude Code ou perfil de Developer |
Invalid API key | Chave API inválida | Verifique a sintaxe e se a chave foi excluída no Console; execute env | grep ANTHROPIC para checar se algum arquivo .env carregou chaves antigas |
O cenário do relógio de sistema desajustado provocando loops de login é comumente esquecido — máquinas virtuais isoladas frequentemente apresentam essa falha devido ao atraso de dias no relógio local, invalidando instantaneamente os tokens emitidos. Sincronizar o relógio resolve a questão imediatamente.
💡 Resumo em uma frase: Em falhas de acesso, execute
/statuspara verificar a chave ativa. O erro recorrente ocorre devido a variáveisANTHROPIC_API_KEYconfiguradas no shell sobrepondo a assinatura (unset+ limpeza do arquivo de perfil). Em loops de autenticação, verifique o relógio local e o Keychain do macOS.
04 Configuração: Ajustes, hooks ou MCP declarados que não funcionam
Esta categoria trata de configurações ineficazes — alterações no arquivo settings.json, registros de hooks ou servidores MCP adicionados que parecem ser ignorados pelo Claude. A documentação oficial aborda isso sob o título "Depurando Configurações" com um lema básico: verifique primeiro "quais parâmetros foram de fato lidos pelo Claude Code", evitando premissas sobre sua gravação.
Analogia: entregar a tarefa não significa recebimento. Deixar o caderno sobre a mesa e sair não garante a entrega se ele foi colocado na mesa errada, misturado com outras pastas ou substituído. Parâmetros locais funcionam da mesma forma — se não fizerem efeito, localize "o arquivo exato que a aplicação está lendo", em vez de editar o arquivo que você presume ser o correto.
Comandos para validar dados carregados:
Este é o conjunto de ferramentas para análise de parâmetros. Utilize o comando mapeado para cada recurso:
| Comando | Recurso inspecionado |
|---|---|
/context | Elementos consumindo a janela de contexto atual (prompt do sistema, arquivos ativos, skills, ferramentas MCP, histórico de logs) |
/memory | Arquivos CLAUDE.md e diretrizes de regras carregados na sessão |
/skills | Skills ativas registradas via projeto, usuário ou plugins |
/agents | Configurações e definições de subagents cadastrados |
/hooks | Hooks registrados no escopo da conversa ativa |
/mcp | Servidores MCP ativos e seus respectivos estados |
/permissions | Regras de acesso (permitir/negar) ativas na sessão |
/debug [descrição] | Habilita os logs de depuração detalhados e orienta o Claude a usar logs e caminhos para diagnósticos |
/status | Fontes de configurações ativas na inicialização (incluindo parâmetros gerenciados) |
A abordagem é simples: execute o comando referente ao recurso configurado para checar sua presença. Se um hook registrado não disparar, execute /hooks para verificar o registro — ausência indica falha de leitura; presença sem ativação indica parâmetros de busca (matchers) incorretos.
Problemas recorrentes de configurações locais:
Selecionamos os pontos mais frequentes da documentação técnica oficial:
| Sintoma observado | Causa provável | Correção recomendada |
|---|---|---|
| O hook cadastrado nunca dispara | O matcher foi escrito em minúsculas (como "bash") | Ferramentas são case-sensitive e iniciam com maiúscula: Bash, Edit, Write, Read |
| O hook cadastrado nunca dispara | O hook foi salvo em arquivo separado | Hooks globais ou locais de projeto devem ser inseridos na chave "hooks" do arquivo settings.json |
Os parâmetros do settings.json são ignorados | A mesma diretriz foi salva no arquivo settings.local.json | O arquivo settings.local.json tem precedência sobre settings.json, e ambos sobrepõem o global ~/.claude/settings.json (veja o Artigo 31) |
Servidores MCP do arquivo .mcp.json não inicializam | O arquivo foi salvo incorretamente na pasta .claude/ | O arquivo de definição MCP do projeto deve ficar no diretório raiz do repositório como .mcp.json, não na pasta .claude/ |
| Servidor MCP de projeto não aparece ativo | A aprovação manual explícita foi desativada | Servidores locais exigem permissão inicial. Execute /mcp para validar o status e autorizar (veja o Artigo 22) |
Diretrizes do CLAUDE.md de subpasta não se aplicam | O carregamento é feito sob demanda ("lazy load") | O arquivo é processado apenas quando a ferramenta de leitura (Read) acessa aquele diretório específico, não na inicialização (veja o Artigo 18) |
A sensibilidade a maiúsculas no matcher de hooks é o erro mais comum: registrar um hook do tipo PostToolUse com matcher "edit|write" impedirá o disparo do comando durante as edições de arquivos. A saída do comando /hooks exibirá o registro normalmente e a sintaxe parecerá correta, mas a ferramenta espera nomes capitalized, como "Edit|Write". A documentação enfatiza: "A correspondência diferencia maiúsculas de minúsculas." Compreender essa particularidade economiza horas de depuração.
Tratamento de Permissões: Regras ineficazes ou confirmações excessivas
Os problemas relacionados a permissões enquadram-se nesta categoria, dividindo-se em dois tipos comuns:
1. Falha em bloqueios informados no CLAUDE.md. Conceito importante: avisos como "nunca edite o arquivo .env" gravados no CLAUDE.md são apenas "solicitações", não garantias técnicas. O manual explica que instruções informam o processo de tomada de decisão do Claude, mas restrições obrigatórias exigem regras de permissões ou hooks específicos (veja os Artigos 20 e 21). Para restringir um recurso, not dependa de textos explicativos; cadastre uma regra deny ou use um hook PreToolUse.
2. Regras do tipo deny contornadas por comandos alternativos. Por exemplo, tentar negar exclusões com Bash(rm *) não impedirá comandos como /bin/rm ou find . -delete. O motivo é simples — regras de correspondência de prefixos analisam o texto literal do comando enviado, não o arquivo executável no sistema. A solução envolve especificar regras explícitas para as variações ou adotar hooks PreToolUse e ambientes sandbox estruturados. Inicie o diagnóstico executando /permissions para revisar as regras vigentes.
Isso reforça o conceito abordado no Artigo 50 sobre antipadrões: delegar limites de segurança para instruções em linguagem natural é um erro conceitual — instruções são orientações; restrições reais exigem regras técnicas e hooks.
💡 Resumo em uma frase: Em falhas de parametrização, execute
/context,/memory,/hooks,/mcpou/permissionspara verificar "o que foi carregado de fato". As falhas comuns são matchers de hooks sem iniciais maiúsculas, sobreposição de arquivos locaissettings.local.json, salvamento do arquivo.mcp.jsonfora da raiz e inclusão de bloqueios de segurança no CLAUDE.md em vez de regras explicitamente negadas (deny).
05 Desempenho: Lentidão, consumo de memória ou falha na indexação de arquivos
Esta categoria trata de lentidão na execução — aumento de latência nas respostas, consumo excessivo de memória ou falha de autocompletar na chamada @file. O manual de desenvolvimento enquadra essas falhas em "Desempenho e Estabilidade" — a maioria decorre de sobrecarga de contexto ou particularidades de ambiente, raramente sendo bugs da ferramenta.
Analogia: lentidão de hardware devido a múltiplos processos ativos. Quando o sistema operacional apresenta lentidão, a solução imediata é encerrar programas pesados e limpar a memória cache antes de acionar a assistência técnica. A otimização do Claude Code segue a mesma lógica — limpe o histórico da conversa antes de tentar reinstalar a aplicação.
Lentidão / Consumo excessivo de recursos: Reduza o contexto
O fluxo recomendado de otimização é prático:
- Execute periodicamente o comando
/compactpara condensar o contexto de conversa (veja o Artigo 19). - Reinicie o processo do Claude Code ao mudar para tarefas complexas.
- Insira pastas de build volumosas no arquivo
.gitignorepara ignorá-las na indexação de buscas.
Se o consumo de RAM persistir elevado, utilize o comando /heapdump — ele gravará um snapshot de alocação de memória JavaScript no diretório ~/Desktop (no Linux, será gerado na pasta Home do usuário) para anexar em issues relatadas no GitHub. Este recurso é voltado para depuração avançada e serve apenas como conhecimento.
Instruções para travamentos de processo: Pressione Ctrl+C para cancelar a ação atual. Se não houver retorno, reinicie a janela do terminal. Encerrar a sessão não apagará os dados; acesse o mesmo diretório e execute
claude --resumepara recuperar o histórico anterior.
Loops de compactação automática: Sintomas e soluções
Se visualizar a mensagem Autocompact is thrashing: the context refilled to the limit..., não se preocupe — isso indica que a compactação ocorreu, mas a leitura imediata de logs extensos ou arquivos gigantes saturou o contexto novamente. Para evitar consumo inútil de requisições de API, a aplicação interrompeu o processo. Solução: oriente o Claude a ler arquivos volumosos de forma fatiada (delimitando linhas ou funções específicas), utilize /compact pedindo para "preservar apenas o plano de ação e as diffs", ou use /clear para recomeçar.
Falhas de indexação e buscas no @file: Valide o ripgrep
Se as ferramentas de busca ou as sugestões com @file falharem em localizar arquivos locais, o motivo costuma ser incompatibilidade do binário embarcado do ripgrep com seu sistema operacional. A solução consiste em instalar o pacote oficial ripgrep no sistema e configurar o Claude Code para adotá-lo:
# macOS
brew install ripgrepEm seguida, defina a variável de ambiente USE_BUILTIN_RIPGREP=0 (consulte a configuração de variáveis de ambiente no Artigo 42).
Guia de ações para erros de desempenho:
| Sintoma observado | Ação recomendada |
|---|---|
| Aumento de latência ou consumo de RAM alto | Execute /compact e reinicie a aplicação |
| Travamento completo do terminal | Pressione Ctrl+C; caso persista, reinicie a janela e use claude --resume |
Alerta de Autocompact is thrashing | Solicite leituras fragmentadas e use /compact keep only ... |
Busca ou autocompletar do @file inativos | Instale o ripgrep no sistema e defina USE_BUILTIN_RIPGREP=0 |
| Caracteres corrompidos no terminal integrado | Execute /terminal-setup para desabilitar a renderização por GPU |
O problema de renderização corrompida de fontes costuma ocorrer no terminal integrado do VS Code. Executar /terminal-setup para desligar o acelerador de GPU do terminal e recarregar a janela resolve a visualização — trata-se de um detalhe estritamente visual da interface, sem impacto nos recursos da IA.
💡 Resumo em uma frase: Lentidão geralmente indica sobrecarga de dados —
/compact+ reinicialização resolve a maioria dos casos; em travamentos, use Ctrl+C ouclaude --resume; falhas de indexação exigem o binário global doripgrep; fontes corrompidas no terminal são resolvidas com/terminal-setup.
06 API: Mensagens de Erro da API: Diagnóstico de responsabilidade de falhas
Esta categoria trata de avisos explícitos de API Error: ... exibidos na sessão. Diante desses alertas vermelhos, a prioridade é distinguir se a falha é do servidor remoto ou de sua máquina local — as ações de mitigação para cada caso são opostas.
Analogia: instabilidade de internet ou fora do ar. Se o servidor estiver inoperante, recarregar a página repetidamente não trará retorno, restando apenas aguardar. Se a sua conexão local falhar, o foco deve ser o roteador. Erros de chamadas de API seguem essa lógica — mapeie o responsável antes de gastar tempo tentando alterar parâmetros locais.
Rechecado automático ativo por padrão
A aplicação adota políticas automáticas de contingência: em falhas de infraestrutura, indisponibilidades, timeouts e limites excedidos, o Claude Code efetuará até 10 tentativas com recuo exponencial (backoff). Nesses cenários, a interface exibirá o status Retrying in Ns · attempt x/y. Portanto, a exibição final da mensagem de erro indica que todas as tentativas automáticas foram esgotadas, sem desistência imediata por parte da CLI.
Três categorias principais de erros:
Agrupamos a lista longa de erros em três blocos práticos para tomada de ação:
| Mensagem de erro típica | Responsável | Ação recomendada |
|---|---|---|
API Error: 500 / 529 Overloaded / Server is temporarily limiting requests | Servidor (não é local) | Aguarde alguns minutos antes de tentar novamente; valide a página status.claude.com; mude o modelo com /model (pois os limites de cota são isolados por modelo) |
You've hit your session/weekly/Opus limit | Sua conta (cota excedida) | Aguarde a janela de renovação de créditos; use /usage para checar seu saldo ou /usage-credits para carregar saldo ou atualizar o plano |
Prompt is too long / Request too large | Seu comando (volume de dados excedido) | Execute /compact ou /clear; divida a leitura de arquivos muito longos informando linhas específicas, evitando colar trechos massivos de uma vez |
Os fluxos de resolução variam sensivelmente: erros de infraestrutura exigem aguardar; cota estourada exige créditos; e prompts extensos exigem otimização de entrada. Sem classificar o erro, você pode acabar otimizando o contexto enquanto o servidor está inativo, ou reenviando comandos repetidamente quando o saldo acabou.
Em falhas de conexão de rede (Unable to connect to API, fetch failed ou Request timed out), a responsabilidade costuma ser de roteamentos locais, proxies, VPNs ou configurações de firewall. O passo inicial consiste em testar a conectividade com o endpoint da API no terminal ativo:
curl -I https://api.anthropic.comRetornos bem-sucedidos indicam rede operacional (sendo a causa provável de restrições de proxy ou certificados); timeouts ou falhas em Could not resolve host indicam bloqueio de rede. Em conexões sob proxies corporativos, registre a variável HTTPS_PROXY correspondente. Para conexões com alta latência, aumente o tempo limite de conexões da CLI utilizando as duas variáveis oficiais abaixo (veja o Artigo 42 para sintaxe):
| Variável de ambiente | Padrão | Finalidade |
|---|---|---|
API_TIMEOUT_MS | 600000 (10 minutos) | Tempo limite de uma chamada de API. Aumente em redes lentas ou sob proxies restritivos |
CLAUDE_CODE_MAX_RETRIES | 10 | Número de tentativas automáticas. Reduza se quiser falhas rápidas em fluxos de scripts |
Mensagens comuns que geram má interpretação:
1. model not found ou you may not have access to it: Ocorre quando o identificador de modelo configurado é inválido ou sem acesso na conta. Execute /model na sessão interativa para redefinir o modelo ativo. Se o identificador incorreto reaparecer, valide onde ele está registrado seguindo a ordem de precedência: parâmetro --model → variável ANTHROPIC_MODEL → arquivo settings.local.json → chaves model do settings.json. Remova valores obsoletos para reverter ao padrão. A documentação recomenda adotar aliases genéricos (como sonnet ou opus) em vez de identificadores de versões estáticos, pois os aliases mantêm a aplicação atualizada de forma automática (consulte o Artigo 04 para as configurações).
2. Claude Code is unable to respond to this request, which appears to violate our Usage Policy: Indica bloqueio de segurança nos filtros de política de uso. Particularidade importante — esse filtro analisa o histórico acumulado de conversa de toda a sessão, não apenas o último prompt enviado. Assim, simplesmente alterar os termos do prompt na mesma aba continuará resultando em recusa. Solução: Pressione a tecla Esc duas vezes ou use /rewind para retornar ao ponto anterior ao bloqueio (veja o Artigo 37) e reescreva o prompt; se necessário, execute /clear para iniciar uma conversa limpa.
💡 Resumo em uma frase: Divida erros de API em três frentes: falhas
5xx/529dependem do servidor (aguardar, checar status ou trocar modelo); alertas delimitexigem créditos ou tempo de recarga; e erros detoo longexigem limpeza de contexto (/compactou leitura fatiada). ErrosUnable to connectdependem de redes locais (rodecurlpara testar hosts e registre proxies/VPNs); erros de modelo são resolvidos adotando aliases.
07 Técnicas Avançadas: Parâmetro --debug e comparação com ambientes limpos
As diretrizes das categorias anteriores resolvem a maioria das ocorrências. Caso enfrente comportamentos atípicos e difíceis de rastrear, utilize estas duas técnicas de depuração avançada para isolar a causa raiz.
Analogia: depuração elétrica via multímetro e desconexão de carga. Em circuitos elétricos, o eletricista adota dois fluxos — monitorar medições com multímetro (visualização de logs em tempo real) e desconectar componentes um a um para observar se o erro cessa (isolamento de variáveis). As duas técnicas avançadas abaixo baseiam-se nessa metodologia.
1. Parâmetro --debug para monitoramento de execução
Em diagnósticos sem mensagens de erro explícitas, inicie a aplicação com o parâmetro --debug para exibir o fluxo de processamento interno. Adicione sub-flags adicionais para estreitar a análise:
| Comando executado | Finalidade de depuração |
|---|---|
claude --debug | Log geral de fluxo para visualizar o processamento interno |
claude --debug mcp | Exibe a saída padrão de erro (stderr) de conexões de servidores MCP (útil para servidores ativos sem ferramentas visíveis) |
claude --debug hooks | Monitora o acionamento de hooks, verificando correspondências de matchers, saídas e códigos de retorno (útil para hooks inativos) |
Você também pode utilizar o comando /debug [descrição] na sessão ativa: ele habilita os registros de auditoria detalhados e orienta o Claude a usar essas saídas de erro e configurações locais para guiar o diagnóstico.
Exemplo prático: Um hook configurado aparece em /hooks, mas nunca é acionado. Executar claude --debug hooks e acionar uma ferramenta exibirá logs claros sobre qual evento ocorreu, quais correspondências foram verificadas e por que foram ignoradas. Essa transparência é mais eficiente do que analisar o arquivo de configuração manualmente.
2. Comparação com ambientes limpos
Esta técnica permite confirmar se a falha é gerada por configurações personalizadas ou pelo ambiente. O fluxo consiste em iniciar uma sessão sem carregar nenhum parâmetro customizado: se a falha for mitigada, a causa está nos arquivos de parametrização locais. O comando:
cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claudeAo apontar a variável CLAUDE_CONFIG_DIR para uma pasta vazia, a inicialização ignora o diretório de configurações globais ~/.claude. Executar a partir de /tmp (que não contém subpastas .claude, definições .mcp.json ou arquivos CLAUDE.md) evita a leitura de parâmetros locais de projetos. A sessão resultante estará livre de customizações, hooks, MCPs, plugins ou memórias locais.
- Se o erro desaparecer na sessão limpa: A falha está restrita ao conteúdo das pastas
~/.claudeou do projeto. Adicione os arquivos de configuração um por um, executando o Claude após cada inserção para validar qual arquivo reintroduz o erro. - Se o erro persistir na sessão limpa: A causa está fora dos parâmetros de customização (como variáveis de ambiente globais, configurações gerenciadas ou falhas de pacotes instalados).
Esta metodologia de divisão busca reduzir variáveis ativas para isolar o problema. Se o Claude ignorar uma instrução no CLAUDE.md, usar uma sessão limpa permite confirmar se há instruções conflitantes no repositório, poupando a leitura de documentações longas.
💡 Resumo em uma frase: Diante de erros complexos, use:
claude --debug [mcp/hooks]para depurar o fluxo interno de processamento e a comparação com configurações limpas (apontandoCLAUDE_CONFIG_DIRpara pasta vazia) para confirmar se a falha está nas configurações personalizadas.
08 Prática: Execução de diagnóstico completo no seu ambiente
A consolidação exige prática. Siga os passos abaixo para executar o /doctor no seu ambiente e validar os canais de login ativos. O fluxo exige apenas que o Claude Code esteja instalado.
Passo 1: Confirme a versão do claude no terminal
claude --versionSaída esperada: O terminal deve exibir a versão instalada, como 2.1.xxx (Claude Code). Exibir a versão confirma a instalação básica. Mensagens de command not found: claude indicam que o binário não está registrado no PATH. Consulte as instruções do Artigo 02 para registrar o PATH do seu sistema operacional (no macOS/Linux, o binário local costuma ficar em ~/.local/bin).
Passo 2: Inicie a sessão e execute o diagnóstico
claudeDigite no prompt interativo:
/doctorSaída esperada: A interface exibirá o painel de verificação, cobrindo: integridade da instalação, validade dos esquemas de configuração (campos inválidos aparecerão em destaque vermelho), servidores MCP cadastrados e métricas do contexto. Retornos sem marcação de falhas indicam ambiente limpo. Caso identifique erros, pressione f para reportá-los na conversa com o Claude e iniciar a correção.
Passo 3: Identifique a credencial ativa
Execute no prompt:
/statusSaída esperada: Será exibido o método de autenticação vigente. Caso utilize planos pagos Pro/Max, a saída deve registrar OAuth, não uma API key. Se constatar uma API key ativa contrária ao esperado, limpe o ambiente executando unset ANTHROPIC_API_KEY no terminal e remova as linhas de exportação dos arquivos do terminal.
Passo 4 (Opcional): Experimente a inicialização com configurações limpas
Para validar o isolamento abordado na Seção 07, execute:
cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claudeSaída esperada: A sessão aberta estará livre de arquivos CLAUDE.md, comandos customizados ou servidores MCP cadastrados (comandos como /memory ou /mcp retornarão listas vazias). Este ambiente servirá de controle em depurações de configurações. Nota: Sistemas Linux e Windows exigirão um novo login de credenciais (salvas na pasta temporária apontada); no macOS, o Keychain continuará autenticando de forma automática. Encerre o terminal para descartar o diretório temporário, sem prejuízo ao arquivo global ~/.claude.
A execução deste fluxo valida as frentes de Diagnóstico → Credenciais → Isolamento de Variáveis. Diante de falhas no dia a dia, siga esta sequência ordenada para obter soluções rápidas.
💡 Resumo em uma frase: Pratique executando a cadeia:
claude --version→/doctor→/status→ sessão limpa. Lembre-se de que/doctoraponta o rumo da falha e/statusas credenciais vigentes, ajudando a mapear rapidamente as causas primárias de erros.
09 Resumo
Este artigo estruturou um processo metodológico de depuração de falhas — cobrindo desde a triagem da categoria do erro até comandos específicos de suporte e técnicas avançadas.
Revisão dos pontos principais:
| Sintoma observado | Ação recomendada | Detalhe crítico |
|---|---|---|
| Dúvida sobre a origem da falha | Tabela de sintomas + /doctor | Mapeie a categoria antes de testar soluções |
| Loops de login ou organização desativada | Execute /status | Geralmente causado por variáveis ANTHROPIC_API_KEY ocultas |
| Configurações, hooks ou MCPs sem efeito | /context, /hooks, /mcp | Valide o que foi de fato lido; verifique a grafia e maiúsculas |
| Lentidão, alto uso de RAM ou falha de indexação | /compact + reinicialização / trocar o ripgrep | Causado por saturação de contexto ou dependências do sistema |
Mensagem de erro API Error no console | Divida em: Servidor / Cota / Prompt | Erros 5xx exigem checar status; cotas exigem créditos; prompts exigem otimização |
| Comportamento atípico de difícil rastreio | --debug + sessão limpa de controle | Depure os logs ou remova variáveis de configuração |
Agora você deve ser capaz de: Diagnosticar falhas do Claude Code metodologicamente — usando a tabela de sintomas para classificar o erro, /doctor para verificar a integridade e /status as credenciais vigentes; tratar erros pontualmente por categorias; depurar logs com --debug ou criar sessões limpas de teste; e reportar problemas complexos com /feedback. Internalizar este fluxo transformará erros misteriosos em problemas com caminhos de resolução mapeados.
Neste ponto, você já domina a instalação, a utilização fluida e os fluxos de resolução de falhas. Resta agora consolidar os jargões e termos apresentados ao longo do guia.
O próximo artigo 52 "Glossário (Acessível)" unificará termos como CLAUDE.md, janela de contexto, MCP, Subagent, Hook, Checkpoint, auto-compact... dezenas de conceitos presentes no manual. O texto trará definições diretas acompanhadas de analogias cotidianas e estruturadas por temas, servindo de material de referência rápido. Reflita: se alguém perguntar qual a relação entre "tokens e a janela de contexto", você saberia explicar de forma simples?