Si sigues usando Claude Code, te vas a atascar tarde o temprano. Este capítulo no es un diccionario de errores. Es un capítulo para adquirir el orden de diagnóstico con el que se baja del síntoma a la causa.
Con solo tener ese orden, podrás decidir «a qué familia pertenece esto» incluso ante un mensaje de error que ves por primera vez. Los artículos concretos sobre cada caso ya los leerás después.
Qué hacer antes de buscar el mensaje de error
Cuando algo se atasca, mucha gente busca directamente el texto del error. También sirve, pero en la mayoría de los casos es más rápido comprobar antes estas tres cosas.
Si funcionaba, la causa no es el entorno, sino el cambio inmediatamente anterior: la conversación que se alargó, el ajuste que añadiste, la red que cambiaste.
Si es siempre, es configuración o entorno. Si es a veces, es congestión o la conexión, y muchas veces la causa no está de tu lado.
¿Al arrancar, al enviar la instrucción o a mitad de la respuesta? El punto en el que se detuvo casi determina la familia.
El CHECK 3 es el que más rinde. Si sabes en qué punto del bucle reunir, actuar y verificar del capítulo 1 se detuvo, los candidatos se reducen de golpe.
Clasificarlo en una de las cinco familias
Los errores de Claude Code se dividen en cinco según dónde está la causa. Empieza por determinar cuál es.
¿Arranca?
no → problema de la propia aplicación (ve al extra de más abajo)
sí
↓
¿Puedes enviar la instrucción?
no, la rechaza → 1. Autenticación
sí
↓
¿Llega la respuesta?
no, no llega / se corta a mitad → 2. Conexión
te habla de un «límite» → 3. Límites de uso
te dice que es «demasiado larga» → 4. Contexto
sí
↓
falla al usar una herramienta externa → 5. Herramientas y extensiones
Haz la apuesta con este árbol y pasa a la sección correspondiente de abajo. Cada familia tiene su propio patrón de solución, así que mezclarlas te funde el tiempo.
1. Autenticación: no acepta quién eres
El síntoma es que te dice que no has iniciado sesión, o que rechaza las credenciales por inválidas. Lo característico es que se detiene antes de enviar la instrucción.
La sesión ha caducado / has entrado con otra cuenta / has confundido la clave de API con la suscripción / la red de la empresa está bloqueando el tráfico de autenticación
Vuelve a iniciar sesión → comprueba con qué cuenta has entrado → prueba con otra conexión (por ejemplo, compartiendo datos del móvil). Si se arregla con lo tercero, es la familia 2, la de conexión
Como en esta familia la tasa de éxito de volver a iniciar sesión es alta, cuando no funciona se tiende a insistir demasiado. Si lo has probado dos veces y no cede, sospecha de la familia 2. El tráfico de autenticación también pasa por la red.
2. Conexión: no llega o se corta a mitad
Es la familia que más se malinterpreta. No siempre es culpa de tu configuración.
Los síntomas se reparten en tres.
Proxy, TLS o bloqueo de la red corporativa. Es un problema del entorno y se aísla probando con otra conexión.
El servicio está saturado. Lo correcto es esperar; si toqueteas la configuración, solo te quedarán los efectos secundarios.
La conexión se cae durante una respuesta larga. A veces deja de reproducirse si acortas la salida por tramos.
Cada uno lo tratamos por separado en cómo resolver los errores de conexión, proxy y TLS, el error 529 Overloaded y el 500 y Connection closed mid-response.
No intentes arreglar la congestión con la configuración. Si por reproducir un «falla de vez en cuando» tocas diez puntos de la configuración, acabarás sin saber si lo arreglaste tú o lo resolvió el tiempo. Primero deja pasar un rato y reinténtalo, y comprueba si ocurre siempre.
3. Límites de uso: has agotado el cupo
Es la familia en la que te dicen que has alcanzado el límite. No es un error, sino el comportamiento previsto, así que lo que hay que corregir no es la configuración, sino la forma de usarlo.
Lo que hay que retener aquí es que no hay un único tipo de cupo. Existen por separado un cupo de ciclo corto y otro de ciclo más largo. Aunque uno se recupere, si el otro sigue agotado seguirás bloqueado. El «se había recuperado y se ha vuelto a parar» suele ser esto.
El detalle está en cómo resolver el usage limit reached y en la verdad sobre el reinicio anticipado del límite semanal, donde verificamos el cupo semanal con mediciones reales. Reducir el consumo en sí lo tratamos en el capítulo 7.
4. Contexto: la entrada es demasiado larga
Es la familia en la que te rechaza por «demasiado larga». Piénsalo como la ventana de contexto del capítulo 1 manifestándose directamente en forma de síntoma.
Pliega el historial o córtalo y empieza uno nuevo. Lo básico es plegar en un corte del trabajo.
No pegues enteros los archivos ni los logs enormes. Pásale solo el fragmento relevante o haz que lo busque él.
La solución como síntoma está en causas y solución del error Prompt is too long, y el criterio para decidir cuándo plegar, en ¿conviene ejecutar /compact a mano?.
Ten en cuenta además que hay casos en los que la salida se detiene por incumplir las políticas. No es un problema de longitud, así que no lo confundas. Ese es otro patrón distinto.
5. Herramientas y extensiones: lo que has conectado no funciona
Es la familia que aparece después de añadir un servidor MCP o una herramienta externa. Aislarla es fácil: mira si se arregla al quitarla.
Quita todas las extensiones
→ se arregla : la causa son las extensiones. Devuélvelas de una en una para dar con la culpable
→ no se arregla : las extensiones no tienen nada que ver. Vuelve a las familias 1 a 4
Si confirmas que la causa es una extensión, ve a causas y solución de los errores de conexión de MCP. Casi siempre es una de tres: el formato de la configuración, la ruta del comando de arranque o los permisos.
Y aquí no pongas en duda la inteligencia de Claude. Si la extensión no está conectada, Claude se comporta como si esa herramienta no existiera. Que la causa de un «se lo he dicho y no lo hace» fuera la conexión es algo bastante habitual.
Un extra: la aplicación no arranca
Si usas la aplicación de escritorio en lugar de la versión de terminal, a veces se detiene antes de llegar siquiera a Claude Code. Como no es ninguna de las cinco familias, lo hemos dejado fuera del árbol de diagnóstico.
El caso de Windows que exige una reparación está en los pasos para reparar el «no se puede abrir esta aplicación», y el caso en el que se congela por temas de renderizado, en causas y solución del bloqueo por GPU process gone.
Cinco movimientos para cuando sigues atascado
Cuando no identificas la familia, o cuando la identificas pero no se arregla. Pruébalos en orden, de arriba abajo. Están ordenados del más barato al más caro.
Los fallos que vienen del contexto desaparecen con esto. Es el movimiento más barato.
La congestión y los límites se resuelven solo con esto. No toques la configuración.
Si con esto se arregla, queda confirmado que la causa es la red de tu entorno.
El aislamiento de la familia 5. Devuélvelas de una en una: todas juntas no sirve de nada.
Prueba lo mismo en un directorio vacío. Si no se reproduce, la causa está en tu proyecto.
Cambia una sola cosa cada vez. Cuando estás atascado entran las prisas y te apetece cambiar varias a la vez, pero así te quedas sin saber qué fue lo que funcionó y, la próxima vez que aparezca el mismo síntoma, volverás a empezar de cero. A la larga sale muchísimo más barato identificar un único movimiento eficaz.
Si quieres buscar por el texto concreto del error, el recopilatorio de errores frecuentes y sus soluciones te sirve de índice.
Resumen
- Antes de buscar el mensaje de error, mira estas tres cosas: «¿funcionaba hasta hace un momento?», «¿pasa siempre?» y «¿dónde se detuvo?»
- Las causas se reparten en cinco familias: autenticación, conexión, límites de uso, contexto y herramientas. No las mezcles al probar
- Ante la congestión y los límites, lo correcto es esperar. Toquetear la configuración solo deja efectos secundarios
- No hay un único tipo de cupo. Existen por separado uno de ciclo corto y otro de ciclo largo, así que puede volver a pararse tras recuperarse
- La familia de las extensiones se aísla de un golpe viendo si se arregla al quitarlas todas. Devuélvelas de una en una
- Cuando no sales, cinco movimientos de más barato a más caro. Y cambia una sola cosa cada vez
Cuando ya sepas salir de los atascos, toca decidir hasta dónde delegar. Pasa al capítulo 5, «Permisos y seguridad».