Errores de Claude Code: 5 problemas comunes y cómo solucionarlos rápido (2026)

Claude Code lanza actualizaciones rápido, así que los nombres de los comandos y el comportamiento pueden cambiar; te avisaré de todo lo que debas comprobar por tu cuenta. Contrasta con la documentación oficial de Claude Code cuando necesites seguridad.

Búsqueda rápida de errores (síntoma → solución)

Esta es la sección principal de referencia. Encuentra la fila que coincide con el mensaje que ves, sigue la última columna y salta a la sección detallada si quieres entender la causa.

Antes de arreglar nada: ¿problema tuyo o de Anthropic?

El error más común de quien empieza es lanzarse directo a reinstalar y reescribir la configuración cuando el problema, en realidad, vive en el servidor. Antes de cada solución, tómate 30 segundos para clasificarlo:

• Tu lado (entorno/config): command not found, un PATH mal puesto, autenticación rota, un bloqueo de permisos, un contexto lleno. Señal reveladora: se repite de forma constante, el mismo mensaje en cada ejecución.
• Lado de Anthropic (no lo puedes arreglar): un mensaje overloaded, el modelo que no responde aunque tu red esté bien, un error que aparece de la nada cuando no cambiaste nada. Señal reveladora: es repentino y suele resolverse solo en unos minutos.

Tres comandos para triar rápido: claude --version (¿instalado bien?) → /status (¿en qué ruta estoy, me queda cuota?) → abre la página oficial de estado de Anthropic (¿algún incidente del sistema?). Si los tres están bien y sigues atascado, entonces es hora de arreglar tu entorno local.

Error 1 - Instalado, pero claude no se ejecuta (command not found / PATH)

Síntoma. Terminaste de instalar, pero al escribir claude te sale uno de estos mensajes:

# macOS / Linux (zsh, bash)
zsh: command not found: claude

# Windows (PowerShell / CMD)
claude : The term 'claude' is not recognized as the name of a cmdlet...

Lo frustrante: npm informa de una instalación correcta, pero la terminal sigue sin encontrar el comando.

Causa. El paquete acabó en la carpeta global bin de npm, pero esa carpeta no está en tu variable de entorno PATH, así que el shell no tiene ni idea de dónde encontrar el binario de claude. En Windows, una variable de entorno que defines en una ventana suele desaparecer en cuanto abres otra.

Solución. Primero, encuentra la carpeta global bin de npm:

npm config get prefix
# e.g. returns: /Users/you/.npm-global (macOS)
# or: C:\Users\you\AppData\Roaming\npm (Windows)

El comando está en PREFIX/bin (macOS/Linux) o en el propio PREFIX (Windows). Añádelo a tu PATH:

# macOS / Linux - append to the end of ~/.zshrc (or ~/.bashrc)
export PATH="$(npm config get prefix)/bin:$PATH"
# then reload
source ~/.zshrc

# verify
claude --version

En Windows, abre tu perfil de PowerShell y añade la línea equivalente, o añade la ruta de npm a la variable PATH del sistema (Configuración → Variables de entorno) y luego vuelve a abrir la terminal. Pero aquí va mi recomendación práctica: en Windows, ejecuta Claude Code dentro de WSL2 en lugar de PowerShell/CMD nativo: el entorno Linux esquiva casi todos los problemas engorrosos de PATH y permisos propios de Windows.

Si aún no se reconoce después de arreglar el PATH, lo más probable es que la instalación original no quedara limpia. Vuelve a cómo instalar Claude Code de la forma correcta y empieza de nuevo desde cero.

Error 2 - No puedes iniciar sesión / fallos de autenticación (clave de API vs suscripción)

Síntoma. El inicio de sesión se cuelga en el navegador, dice unauthorized, o Claude Code sigue exigiendo una clave de API aunque creas que ya iniciaste sesión con un plan Pro/Max.

Causa. Aquí suelen dar problemas dos orígenes. Uno es una caché de credenciales corrupta: un token antiguo que se quedó atascado. El segundo, y más común, es la confusión entre dos rutas de autenticación: iniciar sesión con una suscripción (un plan Pro/Max a través de tu cuenta) es completamente distinto de usar ANTHROPIC_API_KEY (facturado por token). Si alguna vez definiste la variable de entorno ANTHROPIC_API_KEY, Claude Code puede preferir la ruta de la clave de API e ignorar el plan que pagas.

Solución. Primero, restablece tus credenciales:

claude logout
claude login # sign in again on the route you want (subscription)

Luego, comprueba si una variable de clave de API se está 'colando en la fila':

# macOS / Linux
echo $ANTHROPIC_API_KEY

# Windows (PowerShell)
echo $env:ANTHROPIC_API_KEY

Si quieres usar tu plan Pro/Max pero esta variable tiene un valor, quítala de tu perfil de shell (la línea export ANTHROPIC_API_KEY=... en .zshrc, o la variable de entorno en Windows) y vuelve a abrir la terminal. Por último, ejecuta /status dentro de Claude Code para confirmar que estás en la ruta correcta. Al revés, si a propósito quieres usar una clave de API, asegúrate de que siga siendo válida y tenga crédito.

Error 3 - 'Rate limit reached' / error 429

Síntoma. Vas trabajando y se detiene a mitad de la tarea con un mensaje Rate limit reached o un código 429, a veces incluso cuando apenas lo has usado.

Causa. La trampa es que dos sistemas distintos muestran la misma línea, pero la forma de manejarlos es la opuesta:

Solución. Primero identifica tu ruta con /status. Luego caza los procesos huérfanos: Claude Code a veces deja un proceso corriendo en segundo plano después de que cierras la ventana, y sigue contando contra tu cuota:

# macOS / Linux - list live claude processes
ps aux | grep claude
# see a stray PID? kill it: kill <PID>

# Windows: open Task Manager, find lingering node/claude processes and end them

Si tu ruta es un plan de suscripción y de verdad te quedaste sin cuota, no hay truco más allá de esperar a que la ventana se reinicie o cambiar temporalmente a un modelo más ligero para ahorrar uso. Con una clave de API, subir el límite es cuestión del tier de tu cuenta. Para saber exactamente de qué regla vino un 429 concreto, contrasta con las issues del repositorio anthropics/claude-code.

Error 4 - Claude Code se cuelga / se atasca a mitad de la tarea (contexto lleno)

Síntoma. La sesión se congela, las respuestas van a paso de tortuga, el modelo empieza a 'olvidar' lo que dijiste al principio, o cae en un bucle sin fin de editar y reeditar que nunca termina.

Causa. Normalmente es una ventana de contexto llena: tuviste una conversación larguísima, pegaste un archivo enorme o le pasaste una tarea tan grande que la salida se dispara. Esto no es un error del servidor, así que no lo confundas con un mensaje overloaded del lado de Anthropic.

Solución. De lo más ligero a lo más pesado:

• /compact - comprime la conversación, conservando los puntos clave pero liberando espacio. Úsalo cuando aún quieres continuar la línea de trabajo actual.
• /clear - borra el contexto y empieza de cero. Úsalo cuando pasas a una tarea sin relación.
• Divide la tarea en partes secuenciales. En vez de 'refactoriza el módulo entero', pásale un archivo a la vez. Aquí, prevenir es mejor que curar.
• Evita pegar un archivo enorme entero en el chat: deja que Claude Code lea el archivo por sí mismo cuando lo necesite, en lugar de meterlo todo en el contexto.
• Si está totalmente congelado: sal de la sesión (Ctrl+C) y vuelve a abrirla. Pierdes el contexto actual, pero pones fin de forma decisiva al estado atascado.

Si quieres profundizar en gestionar el contexto para evitar cuelgues, el flujo metódico y apto para principiantes de 10 pasos para empezar con Claude Code te ayudará a traspasar el trabajo de forma limpia desde el principio.

Error 5 - Bloqueado por permisos (no puedes ejecutar un comando)

Síntoma. Claude Code pide confirmación antes de cada comando, o se niega en redondo a ejecutar un comando / editar un archivo, interrumpiendo tu ritmo.

Causa. Esto normalmente no es un 'bug': es una función de seguridad: el modo de permisos está bloqueando una operación arriesgada hasta que concedes acceso. Por defecto, Claude Code es cauteloso con los comandos que podrían modificar/borrar archivos o ejecutar un shell.

Solución. Concede acceso de forma controlada:

• Cuando Claude Code pregunte, elige acceso por sesión para las operaciones en las que confías, en vez de pulsar aprobar cada dos por tres.
• Añade los comandos que más usas a una allowlist para que deje de preguntar.
• Entiende los distintos modos de permisos para poder elegir el nivel que encaja con lo que estás haciendo.

Una advertencia honesta: no actives el modo que se salta todas las confirmaciones solo para 'ir más rápido'. Deja que Claude Code ejecute cualquier comando sin preguntar: cómodo, pero un riesgo real si el modelo hace algo que no anticipaste en una máquina o repositorio importante. Úsalo solo en un entorno aislado (un sandbox/contenedor).

Configurar permisos de forma segura tiene varias capas, así que lo desarrollo en una guía dedicada y a fondo sobre permisos y modos de permisos de Claude Code que configuras una vez y en la que confías a largo plazo.

¿Sigues con pequeños errores? Checklist y cuándo reinstalar

Si pasaste por los 5 grupos de arriba y aún cazas pequeños errores raros, ejecuta todo este checklist antes siquiera de pensar en reinstalar:

• Actualiza a la última versión: npm i -g @anthropic-ai/claude-code - muchos bugs se arreglan en versiones posteriores.
• Comprueba que Node esté en una versión LTS (algunos errores desconcertantes vienen de que Node sea demasiado viejo o demasiado nuevo).
• Mantén una terminal ejecutando Claude Code por proyecto para evitar conflictos y procesos huérfanos.
• Limpia la caché de credenciales con claude logout y vuelve a iniciar sesión.
• Reinstalación limpia: desinstala del todo y luego reinstala siguiendo la guía de instalación de Claude Code.
• ¿No tienes claro cómo funciona la herramienta de verdad? Relee qué es Claude Code para hacerte el modelo mental correcto: muchos 'errores' son en realidad malentendidos sobre cómo opera.

Cuándo contactar con el soporte de Anthropic: un error que persiste incluso en una máquina limpia, mensajes overloaded repetidos durante horas, o un problema de facturación/cuenta que no puedes ajustar por ti mismo.

Menos errores y más potencia con un kit prehecho (AgentKit)

Buena parte de los pequeños errores viene de que el entorno de cada máquina es distinto: un PATH torcido, config desperdigada, skills estándar o una statusline que faltan. Si prefieres dejar de pelearte con la configuración manual, el kit AgentKit para Claude Code trae config, skills e incluso un constructor de statusline ya listos que ayudan a estandarizar tu entorno de trabajo, atajando buena parte de los errores engorrosos de config y manteniendo las sesiones más estables. No te 'arregla' los errores de CLI de arriba, pero reduce las probabilidades de que aparezcan de entrada. Si quieres probarlo, puedes darle una oportunidad a AgentKit (20% de descuento por el enlace) y ver si el setup prehecho encaja con tu forma de trabajar.

Preguntas frecuentes (FAQ)

¿Por qué al escribir claude sale command not found?

Porque la carpeta que contiene el comando (el global bin de npm) no está en tu variable de entorno PATH, así que el shell no encuentra el binario. Ejecuta npm config get prefix, añade la carpeta /bin correspondiente al PATH y vuelve a abrir la terminal.

¿Claude Code funciona en Windows / PowerShell?

Sí, pero la experiencia es mucho más fluida con WSL2 que con PowerShell/CMD nativo. WSL2 evita la mayoría de los problemas de PATH y permisos propios de Windows.

¿Cuánto dura el 'Rate limit reached'?

Depende del origen. Si es la cuota del plan Pro/Max, tienes que esperar a que la ventana de tiempo se reinicie. Si es el límite de RPM/TPM de una clave de API, reducir tus peticiones simultáneas lo resuelve al instante. Ejecuta /status para ver con cuál chocaste.

¿Qué hago cuando Claude Code se cuelga?

Normalmente es contexto lleno. Usa /compact para comprimir la conversación o /clear para reiniciar, divide la tarea en partes más pequeñas y evita pegar archivos enormes. Si está totalmente congelado, sal de la sesión (Ctrl+C) y vuelve a abrirla.

¿Un error de inicio de sesión lo causa la clave de API o el plan?

Comprueba la variable ANTHROPIC_API_KEY: si tiene un valor, Claude Code puede tomar la ruta de la clave de API en lugar del plan que pagaste. Para usar tu plan Pro/Max, quita esa variable y luego ejecuta claude logout y claude login otra vez.

¿Cómo reinstalo Claude Code?

Desinstala el paquete antiguo, ejecuta npm i -g @anthropic-ai/claude-code de nuevo, asegúrate de que Node esté en una versión LTS y confirma que la carpeta global bin de npm está en tu PATH. Después ejecuta claude login desde cero.

Conclusión + próximos pasos

En resumen: no arregles al azar. Clasifica primero - ¿problema tuyo o de Anthropic? - y luego arregla por el grupo de síntoma correspondiente: no se ejecuta/PATH, autenticación, límite de uso, cuelgue/contexto o permisos. Los tres comandos claude --version, /status y /compact resuelven la mayoría de las situaciones del día a día. Si estás chocando con errores justo al instalar, vuelve a la guía de instalación de Claude Code; y si estás empezando y quieres evitar errores de raíz, sigue los 10 pasos para principiantes. Para estandarizar tu entorno y reducir los pequeños errores a largo plazo, échale un vistazo a la review de AgentKit para Claude Code.