Resolução de Problemas com Claude Code

Problema. O Claude Code parou de funcionar e você não sabe por quê. A maioria dos problemas vem de cinco lugares, e uma lista de verificação rápida resolve isso. Siga a lista em ordem e em poucos minutos você já estará digitando prompts de novo.

Lista de diagnóstico rápido:

# 1. Check your installation
claude --version
 
# 2. Test your internet connection
ping claude.ai
 
# 3. Verify your API key
echo $ANTHROPIC_API_KEY
 
# 4. Clear session state (inside Claude Code)
/clear
 
# 5. Restart with fresh config
claude config

Se algum desses comandos falhar, vá direto para a seção correspondente para encontrar a correção exata.

Problemas de Instalação

Erro. command not found: claude

O binário nunca chegou ao seu PATH, ou a instalação falhou por completo. O instalador nativo resolve isso sozinho:

# Reinstall with native installer (recommended)
curl -fsSL https://claude.ai/install.sh | bash  # macOS/Linux
# Windows PowerShell: irm https://claude.ai/install.ps1 | iex
 
# Verify installation
which claude

Erro. Node.js version not supported

Node 18 ou superior é o mínimo exigido. Verifique o que você tem:

# Check current version
node --version
 
# If below 18.0, install latest Node.js
# Visit nodejs.org and download the LTS version

Erro. EACCES permission denied

No macOS e Linux, a propriedade do npm costuma ser a culpada:

# Fix npm ownership
sudo chown -R $(whoami) ~/.npm
 
# Alternative: use a version manager like nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

No Windows, abra o Prompt de Comando como Administrador e execute o instalador novamente.

Problemas de Autenticação

Erro. Invalid API key

Sua chave pode não estar definida ou estar incorreta. Configure-a corretamente:

# Reconfigure Claude Code
claude config
 
# Or set environment variable
export ANTHROPIC_API_KEY="your-api-key-here"

Pegue uma chave nova em console.anthropic.com. Fique atento a espaços extras ao colar.

Erro. Subscription not recognized

Para falhas de autenticação no Max e Pro:

1. Saia do Claude no navegador, completamente
2. Limpe cookies e dados em cache
3. Abra uma janela privada e entre novamente
4. Execute claude config de novo para finalizar o processo

Problemas de Conexão

Erro. 503 Service Unavailable

Isso é do lado da Anthropic, não seu:

• Aguarde 2 a 5 minutos e os servidores costumam se recuperar
• status.anthropic.com confirma se algo está fora do ar
• Reinstalar não resolve um problema no servidor

Claude Code abre mas fica em silêncio

Limpe o estado da sessão:

# Clear conversation history (run inside Claude Code)
/clear
 
# Or restart with fresh session
exit
claude

Ainda nada? Confirme que sua conexão está ativa e tente de novo.

Problemas de Desempenho

Respostas lentas ou travadas

Escolha um modelo mais rápido e reduza o contexto:

# Use Claude Sonnet 4 for speed
claude --model claude-sonnet-4-20250514
 
# Compress conversation history (run inside Claude Code)
/compact keep only function names and current errors

Erro. Context window full

A conversa ficou grande demais. Redefina ou compacte:

# Quick fix: start fresh (run inside Claude Code)
/clear
 
# Better fix: compress intelligently
/compact preserve main components and recent changes only

Erros de Permissão em Arquivos

Erro. Permission denied on file operations

A propriedade do diretório está errada. Corrija:

# Check current permissions
ls -la
 
# Fix ownership of project directory
sudo chown -R $(whoami) .
 
# Verify Claude Code can access files
claude --add-dir $(pwd)

Problemas de Configurações

Configurações com comportamento estranho

Na maioria das vezes, a precedência de escopo é a razão. A ordem é: Gerenciado > Linha de comando > Local > Projeto > Usuário. Então uma chave em .claude/settings.local.json prevalece sobre a mesma chave em .claude/settings.json, que por sua vez prevalece sobre ~/.claude/settings.json.

# Check which settings files exist
ls ~/.claude/settings.json
ls .claude/settings.json
ls .claude/settings.local.json

Configurações gerenciadas sobrepondo suas preferências

Se a TI enviou um managed-settings.json, ele fica no topo da pilha e você não pode substituí-lo. Arquivos gerenciados ficam em /Library/Application Support/ClaudeCode/ no macOS, /etc/claude-code/ no Linux e WSL, e C:\Program Files\ClaudeCode\ no Windows. Se uma configuração continua voltando ao valor original, pergunte ao administrador se alguma política está fixando ela.

Autocomplete de configurações não funciona

Adicione uma linha $schema no topo do seu settings.json para que o editor possa validar e completar automaticamente:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json"
}

Problemas de Sandbox e Segurança

Erro. bubblewrap not installed (Linux/WSL2)

O sandbox no Linux depende dos pacotes bubblewrap e socat. Instale os dois e execute novamente:

# Debian/Ubuntu
sudo apt install bubblewrap socat
 
# Fedora
sudo dnf install bubblewrap socat

Watchman conflitando com o sandbox

O Watchman da Meta conflita com o sandbox do Claude Code. Desative o Watchman ou mantenha-o fora do limite do sandbox.

Comandos Docker falhando dentro do sandbox

O Docker precisa rodar fora do sandbox. Coloque-o em excludedCommands dentro do settings.json:

{
  "sandbox": {
    "enabled": true,
    "excludedCommands": ["docker", "docker-compose"]
  }
}

Variáveis de Ambiente para Debug

Preso em um bug difícil? Essas variáveis ajudam a isolar o problema:

# Run Claude Code with all non-essential traffic disabled
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 claude
 
# Or set just the auto-updater off
DISABLE_AUTOUPDATER=1 claude

Acha que é um problema de proxy ou rede? Roteie o tráfego com HTTP_PROXY ou HTTPS_PROXY, e use NO_PROXY para ignorar o proxy em hosts específicos.

Correções Avançadas

Ainda quebrado? Limpe tudo e comece do zero:

# 1. Uninstall any existing installation
npm uninstall -g @anthropic-ai/claude-code  # if installed via npm
 
# 2. Remove config files
rm ~/.claude.json
rm -rf ~/.claude/
 
# 3. Fresh install with native installer (recommended)
curl -fsSL https://claude.ai/install.sh | bash  # macOS/Linux
# Windows PowerShell: irm https://claude.ai/install.ps1 | iex
 
# 4. Reconfigure
claude config

O instalador nativo configura o PATH automaticamente e se mantém atualizado.

Verificação de Sucesso

Depois de aplicar a correção, faça um teste rápido:

# Test basic functionality
claude "write hello world in Python"
 
# Test file operations
echo "# Test" > test.md
claude "read and improve test.md"
 
# Test help command (inside Claude Code)
/help

Claude Code deve estar respondendo normalmente agora. Se ainda não estiver, o problema provavelmente é do lado do serviço. Aguarde alguns minutos. Tente de novo.