Claude Code — Erros de Instalação e Como Resolver
Claude Code — Erros de Instalação e Como Resolver
Você seguiu todos os passos do tutorial, digitou o comando de instalação, apertou Enter… e recebeu uma mensagem de erro vermelha no terminal. Frustrante, mas extremamente comum. A maioria dos problemas com o Claude Code acontece nos primeiros cinco minutos — e quase todos têm solução rápida quando você sabe onde procurar.
Este guia reúne os erros mais frequentes durante a instalação e configuração do Claude Code, com comandos prontos para copiar e colar. Se o Claude Code não funciona na sua máquina, há uma boa chance de que a resposta esteja aqui.
*Você permanecerá neste site.
Erro de autenticação ao conectar com a API
Esse é, disparado, o problema número um. Você instala o Claude Code, executa o primeiro comando e recebe algo como Authentication failed ou Invalid API key. Existem três causas principais.
Chave de API ausente ou mal configurada
O Claude Code precisa de uma chave de API válida da Anthropic para funcionar. Se você não configurou essa chave como variável de ambiente, o terminal simplesmente não consegue se autenticar.
Como verificar:
echo $ANTHROPIC_API_KEY
Se o retorno for vazio, a variável não existe. Para configurá-la:
# Linux/Mac — adicione ao final do seu .bashrc ou .zshrc
export ANTHROPIC_API_KEY="sk-ant-sua-chave-aqui"
# Depois recarregue o arquivo
source ~/.bashrc
No Windows (PowerShell):
$env:ANTHROPIC_API_KEY = "sk-ant-sua-chave-aqui"
Nunca compartilhe sua chave de API em repositórios públicos, prints de tela ou fóruns. Se vazar, revogue imediatamente no painel da Anthropic e gere uma nova.
Chave expirada ou sem créditos
Mesmo com a variável configurada corretamente, a autenticação falha se sua conta na Anthropic não tiver créditos disponíveis ou se a chave foi revogada. Acesse o painel em console.anthropic.com e verifique:
- Se a chave ainda está ativa
- Se há saldo ou plano de cobrança configurado
- Se não há restrições de IP na sua conta
Proxy ou firewall bloqueando a conexão
Em redes corporativas, proxies e firewalls podem bloquear requisições para a API da Anthropic. Sintomas típicos: timeout longo seguido de erro de conexão.
Se você usa proxy, configure no terminal antes de executar o Claude Code:
export HTTPS_PROXY="http://seu-proxy:porta"
export HTTP_PROXY="http://seu-proxy:porta"
Conflitos de versão do Node.js e npm
O Claude Code roda sobre Node.js. Se sua versão estiver desatualizada ou incompatível, a instalação pode falhar silenciosamente — ou com mensagens enigmáticas.
Qual versão do Node.js usar
| Versão do Node.js | Compatibilidade com Claude Code | Recomendação |
|---|---|---|
| 16.x ou inferior | ❌ Não compatível | Atualize imediatamente |
| 18.x LTS | ✅ Compatível | Funciona, mas considere atualizar |
| 20.x LTS | ✅ Totalmente compatível | Recomendada |
| 22.x | ✅ Compatível | Versão mais recente |
Verifique sua versão atual:
node --version
npm --version
Como atualizar o Node.js sem quebrar nada
A forma mais segura é usar o nvm (Node Version Manager), que permite alternar entre versões sem conflito:
# Instalar o nvm (Linux/Mac)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# Reinicie o terminal, depois:
nvm install 20
nvm use 20
nvm alias default 20
No Windows, use o nvm-windows com os mesmos comandos de instalação e troca de versão.
Erro “npm ERR! code ERESOLVE”
Esse erro indica conflito entre dependências. A solução mais direta:
npm install -g @anthropic-ai/claude-code --legacy-peer-deps
Se persistir, limpe o cache do npm antes de tentar novamente:
npm cache clean --force
Sempre que atualizar o Node.js, reinstale os pacotes globais. O nvm não migra pacotes automaticamente entre versões. Use nvm reinstall-packages para facilitar.
Problemas de permissão no terminal
Erros como EACCES: permission denied ou Error: EPERM aparecem quando o npm tenta gravar em diretórios protegidos do sistema. Isso é especialmente comum no Linux e Mac.
Nunca use sudo com npm install -g
Parece tentador resolver com sudo npm install -g, mas isso cria uma cascata de problemas de permissão futuros. A solução correta é reconfigurar o diretório global do npm.
Opção 1 — Alterar o diretório padrão do npm:
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
Adicione ao seu .bashrc ou .zshrc:
export PATH=~/.npm-global/bin:$PATH
Recarregue e reinstale:
source ~/.bashrc
npm install -g @anthropic-ai/claude-code
Opção 2 — Usar nvm (recomendada):
Se você instalou o Node.js via nvm, os pacotes globais já são armazenados no diretório do usuário. Nenhuma configuração extra é necessária.
Permissões no Windows
No Windows, o erro de permissão geralmente aparece quando o terminal não está em modo administrador. Abra o PowerShell como Administrador (clique direito → “Executar como administrador”) e tente novamente.
Se usar o WSL (Windows Subsystem for Linux), siga as instruções da seção Linux acima — o ambiente é idêntico.
*Você permanecerá neste site.
Como reinstalar o Claude Code de forma limpa
Quando nenhuma das soluções acima funciona, o caminho mais eficiente é uma reinstalação completa. O processo remove todos os resquícios da instalação anterior e recomeça do zero.
Passo a passo para reinstalação limpa
1. Remova o pacote global:
npm uninstall -g @anthropic-ai/claude-code
2. Limpe o cache do npm:
npm cache clean --force
3. Verifique se não sobrou nada:
which claude # Linux/Mac
where claude # Windows
Se ainda retornar um caminho, delete o arquivo manualmente.
4. Verifique o Node.js:
node --version # Precisa ser 18+ (recomendado 20+)
npm --version # Precisa ser 8+
5. Reinstale:
npm install -g @anthropic-ai/claude-code
6. Configure a chave e teste:
export ANTHROPIC_API_KEY="sk-ant-sua-chave-aqui"
claude --version
Se o comando claude --version retornar o número da versão sem erros, a instalação está funcional.
Execute claude --verbose para ver logs detalhados de cada etapa. Isso ajuda a identificar exatamente onde o processo trava — se é na autenticação, na conexão de rede ou em alguma dependência local.
Tabela resumo: erros e soluções rápidas
| Erro | Causa provável | Solução |
|---|---|---|
Authentication failed |
Chave de API ausente ou inválida | Configurar ANTHROPIC_API_KEY |
npm ERR! code EACCES |
Permissão negada no diretório global | Reconfigurar prefix do npm ou usar nvm |
npm ERR! code ERESOLVE |
Conflito de dependências | Usar flag --legacy-peer-deps |
command not found: claude |
PATH não inclui diretório do npm global | Adicionar ~/.npm-global/bin ao PATH |
Timeout / Connection refused |
Firewall ou proxy bloqueando | Configurar variáveis de proxy |
Unsupported engine |
Node.js desatualizado | Atualizar para Node.js 20+ via nvm |
Quando o problema não é a instalação
Se tudo instalou corretamente mas o Claude Code trava ao executar comandos, o problema pode estar em outro lugar: configuração do projeto, permissões de leitura nos arquivos do repositório ou até limites de taxa (rate limits) na API. Esses cenários são diferentes de erros de instalação e exigem abordagens específicas de debug no ambiente de desenvolvimento.
O ponto principal: separe mentalmente “erro de instalação” de “erro de uso”. Se claude --version funciona, sua instalação está íntegra. O problema está na etapa seguinte.
*Você permanecerá neste site.
Artigos relacionados
- Claude Code – Guia Completo para Criar Projetos com IA
- Como Instalar e Configurar o Claude Code do Zero
- Como Configurar o Ambiente Ideal para Claude Code
Bruno Bracaioli
Empreendedor e Desenvolvedor
Bruno Bracaioli é especialista em arquitetura de software, ciência de dados e cybersecurity. Além disso, investe em criptomoedas e em investimentos tradicionais como CDBs, Ações, Tesouro e outros. É influenciador digital no instagram (@brunobracaioli) e no Youtube (/brunobracaioli). Contato por: bruno@bracaiolitech.com ou pelo bruno@b2tech.com