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

Este error solo afecta a la instalación por npm. Recomendamos Node.js 22 LTS o superior. Compruébala con node --version (con nvm: nvm install 22 && nvm use 22). El instalador nativo no necesita Node.js.

Al iniciar sesión / autenticación

Errores de inicio de sesión o "Invalid API key"

• Ejecuta claude y completa el inicio de sesión en el navegador; dentro de una sesión puedes usar /login.
• Si querías usar tu suscripción pero Claude pide aprobar una clave, comprueba sin mostrar su valor si existe: test -n "$ANTHROPIC_API_KEY" && echo "API key configurada".
• Si usas API, revisa en Console que la clave siga activa y que la cuenta tenga saldo.
• No pegues ni muestres una API key en capturas, chats o tickets de soporte.

"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 install -g @anthropic-ai/claude-code@latest

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: