SpyBara
Go Premium

troubleshooting.md 2026-10-01 23:59 UTC to 2026-10-02 03:59 UTC

This page contains 44 additions and 21 deletions.

2026
Fri 2 04:57

Solução de problemas

Corrija alto uso de CPU ou memória, travamentos, ciclos repetidos de compactação automática e problemas de pesquisa no Claude Code, e encontre a página certa para outros problemas.

Esta página aborda problemas de desempenho, estabilidade e pesquisa depois que o Claude Code está em execução. Para outros problemas, comece pela página que corresponde ao ponto em que você está com dificuldades:

Sintoma Acesse
command not found, falha na instalação, problemas de PATH, EACCES, erros de TLS Solucionar problemas de instalação e login
O download da atualização ou da instalação falha com The connection dropped while downloading the update ou aborted Referência de erros
Loops de login, erros de OAuth, 403 Forbidden, "organization disabled", credenciais do Amazon Bedrock, do Agent Platform do Google Cloud ou do Microsoft Foundry Solucionar problemas de instalação e login
Configurações não sendo aplicadas, hooks não sendo disparados, servidores MCP não carregando Depurar sua configuração
A sessão iniciou no modo auto, ou o Claude edita arquivos e executa comandos sem perguntar Em qual modo uma sessão inicia
API Error: 5xx, 529 Overloaded, 429, erros de validação de requisição Referência de erros
model not found ou you may not have access to it Referência de erros
Um comando executado pelo Claude falha com Your disk quota is full, is full (ENOSPC) ou Command output was lost Referência de erros
A extensão do VS Code não se conecta ou não detecta o Claude Integração com o VS Code
Claude Code process exited with code 1 no VS Code ou em um aplicativo SDK Referência de erros
Plugin do JetBrains ou IDE não detectado Integração com o JetBrains
Alto uso de CPU ou memória, respostas lentas, travamentos, pesquisa que não encontra arquivos Desempenho e estabilidade abaixo

Se você não tiver certeza de qual se aplica, execute /doctor dentro do Claude Code para uma verificação automatizada da sua instalação, configurações, extensões e uso de contexto; ele propõe correções que pode aplicar após sua confirmação. Se o claude não iniciar de forma alguma, execute claude doctor no seu shell. Execute /mcp para verificar o status dos servidores MCP.

Desempenho e estabilidade

Essas seções cobrem problemas relacionados ao uso de recursos, responsividade e comportamento de pesquisa.

Alto uso de CPU ou memória

Claude Code é projetado para funcionar com a maioria dos ambientes de desenvolvimento, mas pode consumir recursos significativos ao processar grandes bases de código. Se você está experimentando problemas de desempenho:

  1. Use /compact regularmente para reduzir o tamanho do contexto. Se retornar Not enough messages to compact., a conversa tem muito poucas voltas para resumir; isso pode acontecer mesmo com um contexto completo quando uma única colagem grande o preencheu
  2. Feche e reinicie Claude Code entre tarefas principais
  3. Considere adicionar grandes diretórios de compilação ao seu arquivo .gitignore
  4. Reinicie com claude --safe-mode para verificar se um plugin, servidor MCP ou hook é a origem. Isso desabilita todas as personalizações para a sessão; se o uso diminuir, veja Debug your configuration para encontrar qual é

Se a memória heap de uma sessão ultrapassar 2.5GB, um aviso crítico de uso de memória aparece. Para liberar a memória, reinicie Claude Code e execute claude --continue para retomar a conversa em um novo processo.

Fora da renderização em tela cheia, executar /compact também libera memória. O aviso desaparece assim que o uso de memória volta a ficar abaixo de 2.5GB.

Se o uso de memória permanecer alto após essas etapas, execute /heapdump para escrever dois arquivos em ~/Desktop: um snapshot de heap JavaScript nomeado <session-id>.heapsnapshot e um detalhamento de memória nomeado <session-id>-diagnostics.json. Claude Code oculta o comando do menu de comandos; digite-o por completo. No Linux sem uma pasta Desktop, os arquivos são escritos em seu diretório home.

O comando também imprime um resumo na conversa, mostrando a memória total do processo, quanto dela está no heap JS e quanto fica fora do heap. O resumo também lista quaisquer indicadores de vazamento, como uma alta taxa de crescimento de memória ou um número inusitadamente alto de identificadores abertos. O resumo diz se a maioria da memória está no heap JS, que o snapshot captura, ou em memória nativa, que não captura.

Relate a saída ou investigue-a você mesmo:

  • Relate-a: abra um problema no GitHub e anexe apenas o arquivo -diagnostics.json, que contém as estatísticas por trás do resumo impresso e nenhum conteúdo de conversa ou credenciais
  • Investigue você mesmo: se o resumo disser que a maioria da memória é heap JS, abra o arquivo .heapsnapshot no Chrome DevTools em Memory → Load e classifique por tamanho retido para ver o que está mantendo a memória

Se o resumo disser que a maioria da memória é nativa, o snapshot não pode mostrá-la; inclua os indicadores de vazamento do resumo em seu relatório.

Tabelas grandes são cortadas no terminal

Uma tabela Markdown com mais de 200 linhas renderiza suas primeiras 200 linhas seguidas por uma linha … N more rows not shown. Apenas a exibição é limitada: a tabela completa permanece na conversa, e /copy copia cada linha. Para uma tabela muito grande para ler no terminal, peça ao Claude para escrevê-la em um arquivo em vez disso. Antes da v2.1.208, Claude Code renderizava cada linha, então retomar uma sessão que continha uma tabela muito grande poderia travar enquanto a re-renderizava.

Auto-compactação para com erro de thrashing

Se você vir Autocompact is thrashing: the context refilled to the limit..., a compactação automática foi bem-sucedida mas um arquivo ou saída de ferramenta imediatamente refilled a janela de contexto várias vezes seguidas. Claude Code para de tentar novamente para evitar desperdiçar chamadas de API em um loop que não está fazendo progresso.

Para recuperar:

  1. Peça ao Claude para ler o arquivo oversized em pedaços menores, como um intervalo de linha específico ou função, em vez do arquivo inteiro
  2. Execute /compact com um foco que descarta a saída grande, por exemplo /compact keep only the plan and the diff
  3. Mova o trabalho de arquivo grande para um subagent para que ele execute em uma janela de contexto separada
  4. Execute /clear se a conversa anterior não for mais necessária

Se o erro voltar após um /clear, execute /context e compare a linha Messages com as linhas acima dela:

  • Messages é a maior linha: um arquivo ou saída de ferramenta na nova conversa está preenchendo novamente a janela, então repita as etapas 1 a 3
  • As outras linhas juntas são maiores: o que é carregado no início da sessão deixa pouco espaço para trabalhar, então reduza o que é carregado na inicialização

Comando trava ou congela

Se Claude Code parece não responsivo:

  1. Pressione Ctrl+C para tentar cancelar a operação atual
  2. Se não responsivo, você pode precisar fechar o terminal e reiniciar

Reiniciar não perde sua conversa. Execute claude --resume no mesmo diretório para retomar a sessão.

Texto garbled ou corrompido no terminal integrado de um editor

Se os caracteres renderizam como caixas, manchas ou glifos incorretos ao executar Claude Code no terminal integrado do VS Code, Cursor ou Devin Desktop, o renderizador GPU do terminal é provavelmente a causa. Execute /terminal-setup dentro do Claude Code para definir terminal.integrated.gpuAcceleration como "off", ou defina-o manualmente nas configurações do seu editor e recarregue a janela. Veja Terminal configuration para as outras configurações que /terminal-setup escreve.

Roda do mouse rola uma linha por vez na renderização em tela cheia

Na renderização em tela cheia, Claude Code rola a conversa em si em vez de deixá-la para seu terminal. Se cada entalhe da roda move menos linhas do que você quer, execute /scroll-speed para aumentar o número de linhas por entalhe e salve-o, ou defina a variável de ambiente CLAUDE_CODE_SCROLL_SPEED, exceto no terminal do IDE JetBrains, onde Claude Code aplica seu próprio tratamento de rolagem e nenhum dos dois tem efeito. Veja Mouse wheel scrolling para os valores que cada um aceita.

Para se mover mais rápido sem alterar a velocidade, pressione PgUp e PgDn para rolar meia tela por vez. Para usar o scrollback nativo do seu terminal em vez disso, execute /tui default para alternar para o renderizador clássico.

Comandos de área de transferência como `pbcopy` falham dentro da sandbox

Quando sandboxing está ativado, utilitários de área de transferência como pbcopy, xclip e wl-copy podem falhar ao alcançar a área de transferência do sistema de dentro de um comando Bash em sandbox, deixando sua área de transferência inalterada após Claude canalizar texto para eles.

Para colocar a saída do Claude em sua área de transferência, peça ao Claude para imprimir o conteúdo em sua resposta, depois execute /copy. /copy escreve na área de transferência do próprio processo Claude Code em vez de um comando em sandbox, então sandboxing não o bloqueia. Ele pode copiar um único bloco de código em vez de toda a resposta, e também escreve o que copiou em um arquivo e imprime o caminho, o que lhe dá um fallback quando a escrita da área de transferência não alcança seu terminal, por exemplo sobre SSH.

Quando Claude canaliza texto para uma dessas ferramentas, adicionar pbcopy *, wl-copy * ou xclip * a excludedCommands não retira, por si só, essa chamada do sandbox.

O texto copiado não chega à sua área de transferência local via SSH

Quando Claude Code é executado em uma máquina remota via SSH, ele não consegue executar uma ferramenta de área de transferência em sua máquina local. Fora do tmux, quando você seleciona texto na renderização em tela cheia ou executa /copy, Claude Code envia o texto ao seu terminal como uma sequência de escape OSC 52. Seu terminal decide se o coloca na sua área de transferência. /copy informa Copied to clipboard quer o texto tenha chegado ou não, e fora do tmux o aviso de seleção exibe sent N chars via OSC 52.

Alguns terminais não atuam sobre o OSC 52. O iTerm2 o ignora até que você ative Settings > General > Selection > Applications in terminal may access clipboard, e o Terminal.app do macOS não o suporta.

Para obter o texto sem OSC 52:

  • Mantenha pressionada a tecla de seleção nativa do seu terminal enquanto arrasta e depois copie com o atalho habitual do seu terminal, como Cmd+C. A tecla é Fn no Terminal.app e Option no iTerm2. Keep native text selection a lista para outros terminais.
  • Defina CLAUDE_CODE_DISABLE_MOUSE=1 na máquina remota para que seu terminal cuide da seleção durante toda a sessão.

Problemas de pesquisa e descoberta

Se a ferramenta Search, menções @file, agentes personalizados ou skills personalizados não estão encontrando arquivos, o binário ripgrep incluído pode não ser executado em seu sistema. Instale o pacote ripgrep da sua plataforma e diga ao Claude Code para usá-lo em vez disso:

brew install ripgrep

Depois defina USE_BUILTIN_RIPGREP como 0, seja em seu environment de shell ou no bloco env do seu settings.json:

{
  "env": {
    "USE_BUILTIN_RIPGREP": "0"
  }
}

Para confirmar que a mudança teve efeito, execute claude doctor em seu terminal e verifique se a linha Search mostra o caminho do seu ripgrep do sistema em vez de OK (bundled).

Resultados de pesquisa lentos ou incompletos em WSL

Penalidades de desempenho de leitura de disco ao trabalhar entre sistemas de arquivos em WSL podem resultar em menos correspondências do que o esperado ao usar Claude Code em WSL. A pesquisa ainda funciona, mas retorna menos resultados do que em um sistema de arquivos nativo.

Soluções:

  1. Envie pesquisas mais específicas: reduza o número de arquivos pesquisados especificando diretórios ou tipos de arquivo: "Search for JWT validation logic in the auth-service package" ou "Find use of md5 hash in JS files".

  2. Mova o projeto para o sistema de arquivos Linux: se possível, certifique-se de que seu projeto está localizado no sistema de arquivos Linux (/home/) em vez do sistema de arquivos do Windows (/mnt/c/).

  3. Use Windows nativo em vez disso: considere executar Claude Code nativamente no Windows em vez de através de WSL, para melhor desempenho do sistema de arquivos.

Obtenha mais ajuda

Se você está experimentando problemas não cobertos aqui:

  1. Execute /doctor para uma verificação de configuração e /mcp para verificar o status do servidor MCP
  2. Use o comando /feedback dentro do Claude Code para relatar problemas diretamente à Anthropic
  3. Verifique o repositório GitHub para problemas conhecidos
  4. Pergunte ao Claude diretamente sobre suas capacidades e recursos. Claude tem acesso integrado à sua documentação.

Para problemas de conta, faturamento ou assinatura, 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 Obter ajuda. Consulte Como obter suporte para o fluxo completo, incluindo quem pode alcançar um agente humano em cada plano.