🔧 Solución de problemas

Al instalar

"command not found: claude"

Instalaste Claude Code pero la terminal no lo encuentra. Causas habituales:

• La instalación de npm no terminó bien. Reinstala: npm install -g @anthropic-ai/claude-code
• La carpeta global de npm no está en tu PATH. Cierra y abre la terminal de nuevo.
• Aún sin solución: comprueba dónde instala npm con npm config get prefix y asegúrate de que esa ruta /bin esté en tu PATH.

"EACCES: permission denied" al instalar

npm no tiene permisos para instalar globalmente. No uses sudo(causa más problemas). En su lugar, lo ideal es instalar Node.js con un gestor de versiones como nvm, que evita estos problemas de permisos.

"Node.js version too old" / versión incompatible

Claude Code necesita Node.js 20 o superior. Comprueba tu versión con node --version. Si es menor, actualiza Node.js (con nvm: nvm install 20 && nvm use 20).

Al iniciar sesión / autenticación

"Invalid API key" o errores de autenticación

• Comprueba que copiaste la clave entera, sin espacios al principio o final.
• Verifica que la variable está bien puesta: echo $ANTHROPIC_API_KEY debe mostrarla.
• Si la pusiste en ~/.zshrc, recarga con source ~/.zshrc o abre una terminal nueva.
• La clave puede estar revocada o agotada. Genera una nueva en console.anthropic.com.

"Rate limit exceeded" / "Too many requests"

Has hecho demasiadas peticiones en poco tiempo, o alcanzaste el límite de tu plan. Espera unos minutos. Si es recurrente, revisa los límites de tu plan o, en API, tu nivel de uso (tier) en el panel de Anthropic.

"Insufficient credit" / saldo agotado

Si usas API, se acabaron tus créditos. Añade saldo o un método de pago en console.anthropic.com. Si usas suscripción, puede que hayas alcanzado el límite de uso de tu plan; espera a que se renueve o sube de plan.

Durante el uso

Claude Code va lento o se "atasca"

• Sesión muy larga: el contexto se ha llenado. Usa /compact para resumirlo, o /clear para empezar limpio (perderás el contexto de la conversación, no tus archivos).
• Tarea muy grande: divídela en partes más pequeñas. Mira cómo escribir buenos prompts.
• Conexión: Claude Code necesita internet estable.

Hace cambios que yo no quería

• Usa /rewind (o Esc Esc) para deshacer al estado anterior. Ver Flujos de trabajo.
• Si usas git: git restore . revierte los cambios no guardados.
• Para el futuro: usa Plan Mode (Shift+Tab) y revisa el plan antes de que actúe.

No me pide permiso / me pide demasiado permiso

Ajusta la lista de permisos. Si te pregunta por cosas que siempre permites (como npm run), añádelas a la lista allow. Si quieres más control, revisa tu configuración. Todo en Permisos.

Una función de la documentación no me aparece

Probablemente tienes una versión antigua. Claude Code se actualiza muy a menudo:

claude --version
npm update -g @anthropic-ai/claude-code

Un servidor MCP no conecta

• Revisa la lista con /mcp dentro de Claude Code.
• Comprueba que el comando del servidor es correcto y que tiene las variables de entorno necesarias (tokens, rutas).
• Mira los detalles en Servidores MCP.

El comodín que siempre funciona

Si te bloqueas con cualquier error, pregúntale a Claude Code directamente. Es literalmente experto en resolver problemas técnicos. Pégale el error completo: