Si sigues con el coding con IA, te encontrarás sin falta con errores. En cuanto sale texto en rojo, se te paran las manos: ese tiempo es el mayor enemigo de la productividad. Pero tranquilo. Los errores con los que te topas en las herramientas de coding con IA, empezando por Claude Code, son en su mayoría la repetición de patrones fijos. Con solo distinguir el tipo, el remedio queda casi decidido de forma mecánica. Este capítulo es el mapa de triaje (clasificación) de problemas que abrirás lo primero cuando te atasques.
Convertirte en alguien que «no se para ante un error»
🧭 Primero, un artículo recopilatorio. El resumen transversal que reúne los errores frecuentes es «Claude Code: recopilación de errores frecuentes y sus soluciones». Este capítulo es el mapa que da la panorámica de cada categoría, y los artículos individuales enlazados tienen ejemplos concretos de mensajes y los pasos. Recomendamos marcarlo como favorito y tirar desde aquí cuando te atasques.
Clasifica los errores por «tipo»
El primer paso del remedio es distinguir «de qué tipo es este error». Si la capa de la causa es distinta, también lo es el lugar donde arreglarlo. Antes de leerte los mensajes en detalle, encaja el error en una de las siguientes 6 categorías. En el momento en que lo encajas, el 80 % del remedio queda decidido.
Directamente no arranca o no existe el comando. Problema de la puerta de entrada. ↓ detalles
No puedes iniciar sesión o se corta la autenticación. Conexión con la cuenta. ↓ detalles
No hay comunicación o el servidor está congestionado. Problema de la ruta y del lado del servidor. ↓ detalles
Alcanzaste el tope o hay horas en que no puedes usarlo. Problema de plan y consumo. ↓ detalles
Demasiado largo o demasiado apretado. Problema de la cantidad de información que entregaste. ↓ detalles
Falla la extensión o la llamada a la herramienta. Problema de las funciones periféricas. ↓ detalles
💡 Truco para distinguir. Con una sola palabra clave del texto del error ya te haces una idea. command not found → ①, authentication/login → ②, connection/network/529 → ③, usage limit → ④, too long → ⑤, MCP/tool → ⑥. Antes de leerte el mensaje entero, busca primero esta palabra.
① Instalación y arranque: no se encuentra el comando
El primer obstáculo es «directamente no arranca». La instalación falló a medias, o el PATH no está configurado, y por más que escribes el comando no responde. Si te atascas aquí no puedes seguir, así que confirma con calma la puerta de entrada.
Síntoma: al escribir claude responde «no existe ese comando».
Causa: el PATH no apunta al lugar de instalación, no se recargó la shell, o la instalación en sí quedó incompleta.
Remedio: reabre la terminal / comprueba el PATH / reinstala. Probando en orden, casi siempre sales.
Síntoma: se detiene con un error durante la instalación / la rechaza por permisos.
Causa: versión de Node.js antigua, falta de permisos, fallo al obtener el paquete por la red.
Remedio: actualiza el entorno de requisitos (Node, etc.) y revisa los permisos de administrador y el método de instalación. En red corporativa, sospecha también del proxy.
🔧 Los pasos detallados, aquí. El diagnóstico y la solución concreta del fallo de instalación y del command not found están recopilados en «Cómo arreglar command not found / error de instalación». Si te atascas al instalar, lo más rápido es reinstalar siguiendo exactamente los pasos del capítulo 2, «Empezar con Claude Code».
② Inicio de sesión y autenticación: la autenticación no pasa
El patrón en el que arranca, pero te rechaza en el inicio de sesión o la autenticación. Se manifiesta como que la autenticación por navegador no va bien, o que tras un rato de uso te cierra la sesión de golpe. Es un estado en el que el «apretón de manos» entre la cuenta y la herramienta está desajustado.
Síntoma: no pasas de la pantalla de login / te rechaza con un error de autenticación / no se abre el navegador de autenticación.
Causa: token de autenticación caducado o corrupto, fallo de la redirección, confusión de plan o de cuenta, desfase horario.
Remedio: cierra sesión una vez y vuelve a entrar / borra las credenciales guardadas y reautentícate / confirma que es la cuenta correcta.
A veces lo que parece un «error de autenticación» es, en realidad, solo que el plan o el objeto del contrato es otro.
Si usas varias cuentas, confirma primero la cuenta con la que estás logueado y el tipo de plan. Mezclar la del trabajo y la personal es una trampa típica.
🔑 Los pasos detallados, aquí. Los pasos para volver a iniciar sesión y reobtener el token cuando la autenticación no pasa están en «Cómo resolver el error de inicio de sesión / autenticación». La mayoría se resuelve reiniciando sesión, pero si no se arregla, sospecha también del lado de la red (③).
③ Conexión y red: no conecta o hay congestión
Aquí la causa se divide en dos —«tu lado» y «el lado del servidor»—, así que la clasificación es crucial. ¿Es tu conexión o tu proxy lo que bloquea, o es el servidor que está momentáneamente congestionado? Lo primero lo arreglas tú; para lo segundo, la política básica es esperar o aligerar.
Síntoma: no conecta / da timeout / la comunicación se corta a medias.
Causa: conexión inestable, bloqueo por proxy o firewall de la empresa, VPN, problemas de certificados o DNS.
Remedio: prueba con otra conexión / desactiva la VPN / revisa la configuración del proxy. En red corporativa, pídele al administrador la lista de destinos permitidos.
Síntoma: devuelve overloaded o un 5xx. Falla aunque tu configuración sea correcta.
Causa: alta carga o incidencia temporal del lado del servidor. No es culpa de tu código ni de tu configuración.
Remedio: espera un poco y reintenta / evita las horas de congestión / consulta la información de incidencias (página de estado).
⚠️ Pauta para clasificar. Si otras webs y servicios van bien pero solo se cae la herramienta de IA, es muy probable que sea del lado del servidor (529/500) y el remedio es «esperar». Si el resto de tus conexiones también van inestables, es de tu lado (conexión, proxy, VPN). Para más detalle, consulta «Error de conexión / red / proxy» y «El significado y el remedio del error 529 overloaded / 500».
④ Límites de uso: alcanzaste el tope
No es un error, sino un aviso de «alcanzaste el límite, así que ahora no puedes usarlo». Cada plan tiene un tope de consumo por cierto tiempo y por semana, y al tocarlo se detiene temporalmente. Como no es una avería, lo correcto no es intentar arreglarlo, sino ajustar el uso y el plan.
Síntoma: aparece «has alcanzado el límite de uso» y no puedes usarlo hasta cierto tiempo.
Causa: llegaste al tope de consumo del plan. Si corres tareas grandes o conversaciones largas en poco tiempo, llegas antes.
Remedio: espera al reinicio / divide la conversación y úsalo de forma ligera / si hace falta, revisa el plan.
Síntoma: alcanzas el tope a mitad de semana / te da la sensación de que el reinicio llega antes o después de lo que creías.
Causa: el cupo semanal a veces no funciona por semana natural, sino con mecánicas como contar desde tu primer uso.
Remedio: entiende bien cómo se cuenta el reinicio y reparte de forma planificada los trabajos de mayor consumo.
📊 El tope se evita casi del todo con «gestión». El significado del tope y cómo pensar el tiempo de espera están en «Qué hacer cuando alcanzas el límite de uso», y cómo se cuenta el reinicio semanal, en «El mecanismo del reinicio anticipado del tope semanal». La forma de usarlo para tocar el tope lo menos posible la tratamos en conjunto en el capítulo 7, «Coste y eficiencia».
⑤ Entrada y contexto: demasiado largo
La cantidad de información que la IA puede manejar de una vez (el contexto) tiene un tope. Si la conversación se alarga o le entregas de golpe un archivo enorme, te rechaza con «la entrada es demasiado larga». Es una señal de que has apretado demasiado, así que el remedio es reducir o trocear lo que entregas.
Síntoma: sale «la entrada es demasiado larga» y la instrucción no se ejecuta.
Causa: acumulación del historial de la conversación, carga de archivos enormes o de muchos archivos, un log pegado demasiado largo.
Remedio: ordena o resume la conversación / empieza una conversación nueva / entrega solo el rango necesario / trocea la tarea en pequeño.
Síntoma: sale un error en el procesamiento en torno al razonamiento (thinking) y la respuesta se interrumpe.
Causa: inconsistencia del estado de la conversación o desajuste interno relacionado con el historial. Ocurre con más facilidad en conversaciones largas.
Remedio: vuelve a empezar la conversación / separa el intercambio en cuestión. La mayoría se resuelve refrescando.
✂️ «Lo largo» se previene con diseño. Las formas concretas de reducir están en «Cómo resolver prompt is too long», y los fallos en torno a thinking, en «Cómo resolver el error de thinking block». La medida de fondo es trocear la tarea en pequeño, y eso enlaza directamente con la forma de dar instrucciones que tratamos en el capítulo 4, «Pedir bien».
⑥ MCP y herramientas: las extensiones no funcionan bien
En MCP (conexión con herramientas externas) y en las llamadas a herramientas puede ocurrir que el propio Claude Code funcione bien pero fallen solo las extensiones periféricas. El truco es pensarlo por separado del error del núcleo. Si primero compruebas «si se reproduce al quitar la extensión», el diagnóstico de la causa avanza de golpe.
Síntoma: no conecta con el servidor MCP / la herramienta conectada no aparece en la lista o no responde.
Causa: error en el archivo de configuración, fallo al arrancar el servidor, falta de rutas o dependencias, credenciales incorrectas.
Remedio: revisa la configuración / comprueba el arranque del servidor por separado / quítalo una vez y clasifica si funciona solo con el núcleo.
Síntoma: falla la llamada a la herramienta / se detiene al pasar el resultado de la llamada.
Causa: inconsistencia en la definición o los argumentos de la herramienta, desajuste del estado de la conversación, fallo temporal del destino conectado.
Remedio: reencauza la conversación / desactiva temporalmente la herramienta en cuestión para clasificar / comprueba el estado del destino conectado.
Síntoma: da error en las comprobaciones de estado en torno a los PR (pull requests).
Causa: a menudo intervienen la configuración o los permisos del CI y las comprobaciones conectadas, o el estado del servicio externo.
Remedio: revisa la configuración y los permisos del lado de la comprobación / reejecuta / comprueba el estado del servicio externo.
🧩 Con las extensiones, «quita y clasifica». Cómo arreglar la conexión MCP, en «Cómo resolver el error de conexión del servidor MCP»; los fallos de las llamadas a herramientas, en «Cómo resolver el error de llamada a herramienta»; y lo relativo a las comprobaciones de PR, en «Cómo resolver el error de comprobación de estado de PR». El uso de las extensiones en sí lo tratamos en el capítulo 6, «Usar las extensiones».
Cómo salir cuando te atascas: las 5 jugadas universales
Aun cuando no puedas identificar la causa al momento, hay «jugadas universales» que probar primero. Muchos errores desaparecen con solo refrescar el estado o aligerar la carga. Cuando no aciertas con la categoría de arriba, prueba estas 5 en orden, de arriba abajo.
Cierra y reabre la herramienta y la terminal. Los desajustes temporales de estado desaparecen en su mayoría con solo esto. La primera jugada de la que sospechar.
Las conversaciones largas son un caldo de cultivo de inconsistencias. Empieza una conversación nueva o resume/ordena el historial (la idea de /compact) para aligerarte. Sirve para ⑤.
No pidas mucho de una vez; divide la tarea en pasos pequeños. Los errores por «demasiado largo o pesado» se evitan de raíz con esto.
Los 529/500 y la congestión los resuelve el tiempo. Espera unos minutos y reejecuta. Consulta también las incidencias en la página de estado. Sirve para ③④.
Si de verdad no lo entiendes, entrega el texto del error entero a la IA o a un buscador. Contrastándolo con el artículo recopilatorio de este capítulo, casi siempre resulta ser un patrón conocido.
🧯 No agobiarse es el mayor remedio. Un error no es una señal de «se rompió», sino una pista de «arregla esto». Distingue la categoría, prueba las 5 jugadas de arriba y, si aun así no va, ve al artículo individual. Con solo asimilar este flujo, el texto en rojo ya no da miedo.
- Ante un error, primero clasifícalo en 6 categorías (instalación, autenticación, conexión, límites de uso, contexto y MCP/herramientas). Con una sola palabra clave ya te haces una idea.
- Cada categoría tiene un síntoma → causa → remedio casi de molde. Lo del lado del servidor, como 529/500, es «esperar»; lo demasiado largo, «dividir y ordenar».
- Aunque no sepas la causa, con las 5 jugadas universales (reiniciar, reencauzar la conversación, trocear en pequeño, esperar y reintentar, entregar el texto del error tal cual) sales en su mayoría.
- Los pasos concretos, al artículo recopilatorio y a cada artículo individual. La gestión del tope, en el capítulo 7; las extensiones, en el capítulo 6.
Cuando dominas cómo lidiar con los errores, el coding con IA avanza de golpe. Lo siguiente es ampliar la capacidad misma de Claude Code. En el siguiente capítulo 6, «Usar las extensiones», hagamos aún más fuerte a nuestro compañero con hooks, plugins, subagents y MCP.