Resolución de problemas comunes (FAQ / Troubleshooting)

📚 Navegación de la serie: El capítulo anterior 50 Antipatrones: usos incorrectos comunes enumeró uno por uno aquellos usos que "parecen correctos pero en realidad te están tendiendo una trampa". Este capítulo continúa hablando de la resolución de problemas: cuando Claude Code realmente falla, cómo seguir las pistas y solucionar los problemas paso a paso desde la raíz. Problemas para instalar, iniciar sesión, bloqueos de permisos, MCP que no conecta, lentitud al ejecutar, errores en texto rojo... Este capítulo te ofrece un mapa de problemas de "síntoma → dónde buscar, qué ejecutar".

Comencemos con un escenario muy típico y en el que es sumamente fácil caer; si lo entiendes, sabrás exactamente qué problema resuelve este capítulo.

Imagina esta situación: acabas de cambiar a una nueva Mac, instalas Claude Code desde el proyecto de tu empresa y, en cuanto lo inicias, aparece This organization has been disabled. Tu primera reacción suele ser: "Vaya, ¿se habrá suspendido mi cuenta?", por lo que vas rápidamente a claude.ai a revisar tu suscripción — todo está en orden, Max sigue activo. Luego sospechas de la red, activas tu VPN e intentas de nuevo, pero sigue apareciendo la misma línea de texto. Después de dar vueltas de esta manera durante casi cuarenta minutos, habiendo reinstalado Claude Code dos veces y estando a punto de abrir un ticket de soporte...

¿Cuál fue la causa raíz? Cuando migraste la configuración de esa Mac antigua, en tu ~/.zshrc había una línea que ya habías olvidado por completo: export ANTHROPIC_API_KEY=..., dejada por un antiguo proyecto de una empresa que ya había sido cancelado hace medio año. La prioridad de las variables de entorno se impuso sobre el inicio de sesión de la suscripción, y Claude Code intentó autenticarse obedientemente con esa key invalidada; por supuesto que se le informó que "esta organización ha sido desactivada". Con un solo unset ANTHROPIC_API_KEY, se solucionó en segundos.

Menciono este ejemplo para que recuerdes una cosa: lo peor al resolver problemas es "adivinar". Esos cuarenta minutos se perdieron adivinando: adivinando la cuenta, adivinando la red... cuanto más adivinas, más te alejas de la verdad. En realidad, Claude Code incluye sus propias herramientas de diagnóstico; un simple /status te dirá "qué credenciales se están utilizando actualmente", sin necesidad de adivinar. Este capítulo te enseñará a arrinconar los problemas siguiendo un proceso, sin adivinar.

Al terminar este capítulo, obtendrás:

• Una tabla de enrutamiento general de "síntoma → dónde buscar": identifica primero tu error, no empieces a probar cosas al azar.
• Los dos comandos de autoayuda que más debes ejecutar primero: el diagnóstico de /doctor y el informe de /feedback, detallando cuándo usar cada uno.
• Una comparación de "problema → solución" organizada en seis categorías (instalación, inicio de sesión y autenticación, permisos, MCP, rendimiento y mensajes de error).
• Cómo utilizar la serie de modificadores de depuración --debug, además del arma secreta de resolución de problemas: el "método de comparación con configuración limpia".
• Una práctica real paso a paso con su salida esperada: realiza tú mismo un diagnóstico de tu instalación utilizando /doctor.

---

01 Primer principio de la resolución de problemas: identifica primero "a qué categoría pertenece el problema" y no pruebes al azar

Para empezar, una conclusión que es más importante que todos los comandos específicos que siguen: cuando encuentres un problema, el primer paso no es intentar repararlo, sino entender "a qué categoría pertenece": ¿es un problema de instalación, de inicio de sesión, de configuración o de la API? Si clasificas mal la categoría, todo el esfuerzo posterior será en vano.

Analogía: ante una fuga de agua, cierra primero la llave de paso, no empieces a levantar los azulejos. Si hay una filtración en alguna parte de la casa, un fontanero experto no llegará a derribar la pared de inmediato; primero determinará si "es del grifo, de la unión o si se filtra desde el piso de arriba". Si se equivoca en el diagnóstico, destrozará los azulejos sin encontrar la fuga. La resolución de problemas en Claude Code funciona igual: clasifica primero y luego actúa.

¿Por qué es esto lo más importante? Porque la documentación oficial de Claude Code está dividida precisamente por categorías: una página para instalación e inicio de sesión, otra para errores de ejecución, otra para configuración y depuración, y otra para rendimiento. Si ni siquiera tienes claro a qué categoría pertenece tu problema, no sabrás qué página consultar. Al principio de la página oficial de resolución de problemas hay una tabla de enrutamiento que he traducido con los casos en los que es más probable que te encuentres:

Síntoma que ves	A qué categoría pertenece / Qué capítulo consultar
command not found: claude, no se puede instalar, problemas de PATH, EACCES	Instalación (ver Capítulo 02 + Sección 02 de este capítulo)
Te pide iniciar sesión repetidamente, 403 Forbidden, organization disabled	Inicio de sesión y autenticación (Sección 03 de este capítulo)
La configuración no tiene efecto, los hooks no se activan, el MCP server no carga, las reglas de permisos no bloquean	Configuración (Sección 04 de este capítulo + Depuración de tu configuración)
API Error: 5xx, 529 Overloaded, 429	Errores de la API (Sección 06 de este capítulo, la mayoría de las veces no es tu culpa)
model not found / you may not have access to it	Errores (Sección 06 de este capítulo, modelo incorrecto o sin acceso)
Lentitud, alto uso de CPU / memoria, la búsqueda no encuentra archivos	Rendimiento (Sección 05 de este capítulo)

El uso es sencillo: busca en la columna izquierda la frase que más se parezca a la que ves en pantalla, y la columna derecha te indicará en qué dirección investigar. Las secciones siguientes de este capítulo detallarán cada categoría de esta tabla.

Cabe mencionar un recordatorio oficial que vale la pena grabar en tu mente: "Si no estás seguro de cuál se aplica, ejecuta /doctor dentro de Claude Code para comprobar automáticamente tu instalación, configuración, servidores MCP y uso de contexto. Si claude no se inicia en absoluto, ejecuta claude doctor desde tu terminal."

Es decir: ¿no puedes clasificar el problema? No te compliques, ejecuta /doctor primero y este te señalará gran parte del camino. En la próxima sección hablaremos específicamente de estos dos comandos de autoayuda.

💡 Resumen en una frase: El primer paso de la resolución de problemas siempre es clasificar primero, no probar al azar — identifica "a qué categoría pertenece" según la tabla de enrutamiento y ve a la sección correspondiente; si realmente no estás seguro, ejecuta primero /doctor.

---

02 Dos comandos de autoayuda: /doctor para diagnóstico y /feedback para reportar

Antes de consultar cualquier documento o preguntar a alguien, Claude Code incluye dos herramientas de "autoayuda". El 90% de los problemas se identifican directamente con /doctor o, si realmente no puedes resolverlos, se reportan mediante /feedback. Familiarizarte con estos dos comandos te ahorrará mucho tiempo.

Analogía: si no te sientes bien, hazte primero un chequeo médico completo. Cuando te duele algo no te sometes a cirugía de inmediato; primero te haces un chequeo: presión arterial, ritmo cardíaco, análisis... el médico solo necesita ver el informe para saber dónde está el problema. /doctor es el dispositivo de chequeo de Claude Code: con un solo comando, comprueba la salud de la instalación, si la configuración tiene errores de sintaxis, si el MCP está conectado y cuánto contexto se está utilizando.

/doctor: diagnóstico con un solo clic

/doctor es el primer comando que debes ejecutar al investigar un problema. Comprueba los elementos que la documentación oficial detalla claramente: estado de la instalación, validez de la configuración (si hay keys inválidas o errores de esquema), configuración de MCP y uso de contexto.

La clave está en si puedes iniciar la aplicación:

• Si puedes entrar a la sesión: escribe directamente /doctor dentro de Claude.
• Si claude no inicia en absoluto (por ejemplo, command not found o se cierra al abrir): escribe claude doctor en tu terminal (shell) — ten en cuenta que este no lleva barra diagonal, ya que es un subcomando independiente de la línea de comandos.

/doctor tiene además un diseño muy útil: cuando detecta un problema, puedes presionar f para enviar el informe de diagnóstico directamente a Claude, permitiéndole guiarte paso a paso para resolverlo. Es el equivalente a que el médico lea el informe contigo justo después del chequeo.

/feedback: si realmente no puedes solucionarlo, repórtalo

Si ya revisaste la documentación, ejecutaste /doctor y el problema persiste, no te frustres solo, usa /feedback para reportarlo a Anthropic. Esto enviará tu historial de chat junto con una descripción del problema; esta es la forma más rápida para que el equipo oficial diagnostique problemas reales (especialmente cuestiones abstractas como "la calidad de las respuestas empeoró repentinamente" sin mostrar ningún error). Este comando también ofrece una opción: abrir un issue de GitHub con la información ya completada. Nota: si utilizas proveedores externos como Bedrock o Vertex, /feedback no enviará la información a Anthropic, sino que la guardará localmente y deberás enviarla manualmente a tu representante de cuenta de Anthropic.

Tal vez hayas oído hablar de /bug — ese es el nombre antiguo para reportar problemas. Ahora la documentación oficial unifica esto bajo /feedback: envía el historial de la sesión y la descripción a Anthropic, o bien abre un issue en GitHub precompletado. Solo necesitas recordar /feedback.

Aquí tienes una tabla de referencia rápida sobre "qué ejecutar primero":

Tu situación	Ejecuta esto primero	¿Qué hace?
No estás seguro de la categoría del problema	/doctor	Diagnóstico completo para indicar la dirección
claude no inicia en absoluto	claude doctor (en la terminal)	Diagnóstico que se puede ejecutar antes de iniciar
/doctor reportó un problema y quieres que Claude te ayude a resolverlo	Presiona f en los resultados de /doctor	Envía el informe de diagnóstico a Claude
No pudiste solucionarlo ni con la documentación	/feedback	Reporta el historial y la descripción a Anthropic
Quieres verificar si el servicio oficial está caído	Abre en tu navegador status.claude.com	Verifica si hay incidentes en la API

Vale la pena recordar la última opción, status.claude.com: cuando te encuentres con muchos errores de servidor del tipo 5xx o 529, lo primero que debes hacer es mirar esta página de estado, en lugar de dudar de ti mismo — muchas veces es el lado de Anthropic el que experimenta inestabilidad, y no tiene nada que ver con tu configuración. Detallaremos esto en la Sección 06.

💡 Resumen en una frase: Antes de investigar, utiliza las dos herramientas de autoayuda: /doctor (o claude doctor en la terminal) para diagnosticar e identificar la dirección, y /feedback para reportar cuando no puedas solucionarlo; si sospechas que el servidor está caído, revisa primero status.claude.com.

---

03 Inicio de sesión y autenticación: peticiones repetitivas de login y organización desactivada

A partir de esta sección, revisaremos los problemas detalladamente por categorías. Comencemos con inicio de sesión y autenticación — esta categoría suele asustar a los principiantes porque los mensajes de error suenan alarmantes (disabled, Forbidden, revoked), pero la verdad suele ser bastante simple.

Analogía: al pasar tu tarjeta de acceso en la oficina, si no abre no significa que te hayan despedido. Puede que la tarjeta se haya desmagnetizado, que hayas tomado una tarjeta antigua por error o que la hora del sistema de acceso no coincida. Que el mensaje diga "acceso denegado" no significa "no tienes permisos". Lo mismo ocurre con los problemas de autenticación: primero verifica "qué credenciales está usando realmente Claude Code para autenticarse" y no pienses de inmediato en el peor de los casos.

Primer paso: mira qué credenciales se están utilizando actualmente

Este es el primer paso universal para los problemas de autenticación, y la solución para ahorrarse rodeos como el del ejemplo inicial. Escribe en la sesión:

/status

Resultado esperado: mostrarará el método de autenticación activo actualmente — ya sea tu suscripción (inicio de sesión OAuth) o alguna API key. Si eres un usuario con suscripción pero aquí muestra que estás usando una API key, el problema está prácticamente localizado.

La trampa clásica: ANTHROPIC_API_KEY se impone silenciosamente sobre la suscripción

Esto es lo que ocurrió en el ejemplo del principio. La documentación oficial explica el mecanismo con total claridad:

Las variables de entorno tienen prioridad sobre /login, por lo que las llaves exportadas en tu archivo de configuración de shell o cargadas desde un archivo .env se utilizarán incluso si tienes una suscripción activa de Pro o Max. En el modo no interactivo (-p), siempre se utiliza la llave cuando está presente.

Por lo tanto, mientras tengas una variable ANTHROPIC_API_KEY en tu entorno (incluso si quedó de algún proyecto hace meses y ya la habías olvidado), Claude Code la utilizará para autenticarse. Si esta key ha expirado o pertenece a una organización desactivada, reportará This organization has been disabled. La solución:

unset ANTHROPIC_API_KEY
claude

Sin embargo, unset solo tiene efecto en la ventana de terminal actual. Para solucionarlo de raíz, debes eliminar la línea export ANTHROPIC_API_KEY=... de tu ~/.zshrc, ~/.bashrc o ~/.profile (en Windows, revisa el archivo de configuración de PowerShell $PROFILE y las variables de entorno del usuario). Después de borrarla, reinicia claude y usa /status para confirmar que ha vuelto a la suscripción. Esta prioridad de credenciales se explicó en el Capítulo 04 (Configuración de API); recuerda consultarlo si tienes problemas de autenticación.

Otros errores de autenticación comunes y sus soluciones

Error	Qué significa	Cómo solucionarlo
Not logged in · Please run /login	No hay credenciales válidas en esta sesión	Escribe /login para iniciar sesión; si esperas autenticarte mediante variables de entorno, confirma que ANTHROPIC_API_KEY esté realmente exportada
OAuth token revoked / has expired	El token guardado ha expirado	Inicia sesión de nuevo con /login; si el error se repite en la misma sesión, ejecuta primero /logout y luego /login
Te pide iniciar sesión repetidamente (entre varios arranques)	El token siempre queda invalidado	Verifica si el reloj del sistema es preciso (la validación del token depende de marcas de tiempo correctas); en macOS, si el Keychain está bloqueado también ocurrirá esto, ejecuta claude doctor para comprobar el acceso al Keychain
403 Forbidden (después de iniciar sesión)	Problema de suscripción / rol / proxy	Los usuarios Pro/Max deben revisar su suscripción en claude.ai/settings; los usuarios de Console deben confirmar que su cuenta tiene el rol Claude Code o Developer
Invalid API key	Key rechazada	Revisa la escritura y confirma que no haya sido revocada en la Console; ejecuta env | grep ANTHROPIC para ver si un archivo .env cargó una key obsoleta

Ese caso de "verificar el reloj del sistema si te pide iniciar sesión repetidamente" se pasa por alto muy fácilmente — en una máquina virtual que ha estado desconectada de la red durante mucho tiempo, es común no poder iniciar sesión por más que se intente, y al final suele ser porque la hora de la máquina está retrasada tres días, lo que hace que el token se considere expirado nada más emitirse. Sincroniza la hora y se resolverá de inmediato.

💡 Resumen en una frase: Para problemas de autenticación, ejecuta primero /status para ver "qué credenciales se están usando"; el mayor obstáculo suele ser que una variable ANTHROPIC_API_KEY residual en la shell se imponga sobre la suscripción (unset + eliminar del archivo de configuración); si el inicio de sesión se pierde repetidamente, prioriza revisar el reloj del sistema y el Keychain de macOS.

---

04 Configuración: las opciones / hooks / MCP "no surten efecto tras escribirlas"

La segunda categoría es la configuración que no se aplica — escribiste reglas en settings.json, configuraste un hook o añadiste un MCP server, pero Claude parece ignorarlo por completo. Esta clase de problemas pertenece a una sección oficial llamada "Depuración de tu configuración", cuyo concepto clave es: primero confirma qué ha cargado realmente Claude Code, no asumas que lo que escribiste ya está activo.

Analogía: entregar la tarea no significa que el profesor la haya recibido. Si dejas la tarea sobre el escritorio y te vas, puede que no se registre porque la colocaste en la mesa equivocada, se mezcló con los cuadernos de otros o fue sobrescrita por otra entrega. Con la configuración pasa lo mismo — si no surte efecto, primero verifica "cuál archivo está leyendo realmente", en lugar de modificar repetidamente el que crees que es correcto.

Comandos para verificar qué se ha cargado realmente

Esta es la caja de herramientas principal para la configuración. Utiliza el comando correspondiente según lo que desees verificar:

Comando	Qué verifica
/context	Qué elementos ocupan el contexto en la sesión actual (instrucciones del sistema, archivos en memoria, skills, herramientas MCP, mensajes)
/memory	Qué archivos CLAUDE.md y reglas se han cargado
/skills	Las skills disponibles provenientes del proyecto / usuario / plugins
/agents	Los sub-agentes configurados y sus opciones
/hooks	Qué hooks están registrados en la sesión actual
/mcp	Los MCP servers conectados y sus estados
/permissions	Las reglas de permitir / denegar vigentes
/debug [descripción del problema]	Activa el registro de depuración en la sesión y pide a Claude que use los registros y las rutas de configuración para diagnosticar
/status	Qué fuentes de configuración están activas (incluyendo si la configuración gestionada está habilitada)

El uso consiste en "ejecutar el comando correspondiente a lo que configuré y no funciona, para ver si aparece". Por ejemplo, si configuraste un hook pero no se ejecuta, usa /hooks para ver si está registrado. Si no aparece, significa que no se ha leído en absoluto; si aparece pero no se ejecuta, entonces es un problema del matcher (patrón de coincidencia).

Errores comunes de configuración para principiantes

De la tabla oficial de "síntoma → causa → solución", he seleccionado las situaciones más frecuentes para los principiantes:

Síntoma	Posible causa	Cómo solucionarlo
El hook nunca se activa	El matcher se escribió en minúsculas (ej. "bash")	Los nombres de las herramientas distinguen mayúsculas y minúsculas y empiezan con mayúscula: Bash, Edit, Write, Read
El hook nunca se activa	El hook se escribió en un archivo independiente	Los hooks del proyecto / usuario deben colocarse bajo la clave "hooks" en settings.json
Los valores en settings.json parecen ignorarse	El mismo parámetro está definido también en settings.local.json	settings.local.json sobrescribe a settings.json, y ambos sobrescriben a ~/.claude/settings.json (ver detalles en el Capítulo 31)
Los MCP servers en .mcp.json nunca cargan	El archivo se colocó dentro del directorio .claude/	La configuración de MCP del proyecto debe ubicarse en la raíz del repositorio bajo .mcp.json, no dentro de .claude/
El MCP server del proyecto no aparece	Se desactivó el aviso de aprobación única	Los servidores a nivel de proyecto requieren aprobación; ejecuta /mcp para verificar el estado y aprobarlos (ver detalles en el Capítulo 22)
Las instrucciones de un CLAUDE.md en un subdirectorio no aplican	Se cargan "bajo demanda"	Solo se cargan cuando Claude lee ese directorio específico con Read, no al iniciar (ver detalles en el Capítulo 18)

El error del "uso de mayúsculas en el matcher del hook" es muy común: la primera vez que se escribe un hook PostToolUse, se define el matcher como "edit|write", y luego ves que no se ejecuta por más que modifiques archivos. En /hooks aparece claramente registrado, y revisando la configuración parece no haber ningún error — al final te das cuenta de que el nombre de la herramienta debe llevar mayúsculas: "Edit|Write". La documentación oficial indica: "La coincidencia distingue mayúsculas y minúsculas". Si no conoces este detalle, perderás horas; si lo sabes, se soluciona en un segundo.

Relacionado con permisos: "Configuré las reglas pero no bloquean o me sigue preguntando"

Los problemas de permisos (permission) también entran en esta categoría, y los principiantes suelen toparse con dos situaciones:

La primera es: "Las restricciones que escribí en CLAUDE.md no bloquearon la acción". Concepto clave: las instrucciones en CLAUDE.md como "nunca edites .env" son una "petición", no una "garantía". La documentación oficial lo deja muy claro: para que Claude "tome la decisión", usa CLAUDE.md; pero si quieres una restricción estricta "sin importar lo que decida", debes usar reglas de permisos o hooks (ver detalles en los Capítulos 20 y 21). Por lo tanto, si quieres bloquear por completo una operación, no confíes en CLAUDE.md; escribe una regla deny de permisos o un hook PreToolUse.

La segunda es más sutil: la regla deny está escrita, pero no bloquea comandos equivalentes. Por ejemplo, si escribes Bash(rm *) para prohibir el borrado, Claude puede seguir borrando usando /bin/rm o find . -delete. Esto ocurre porque las reglas de prefijo comparan cadenas de comandos literales, no el archivo ejecutable subyacente. La solución es agregar reglas explícitas para cada variante, o bien usar un hook PreToolUse o un entorno aislado (sandbox) para obtener una "garantía real". Al investigar permisos, ejecuta primero /permissions para revisar las reglas de permitir / denegar aplicadas actualmente y ver si coinciden con lo que esperas.

Detrás de esto está el mismo concepto del capítulo 50 sobre antipatrones: confiar la "barrera de seguridad" a una instrucción en lenguaje natural es en sí mismo un antipatrón — las instrucciones son flexibles, mientras que las reglas y los hooks son estrictos.

💡 Resumen en una frase: Si la configuración no surte efecto, usa comandos como /context, /memory, /hooks, /mcp y /permissions para verificar "qué se ha cargado realmente"; los errores más frecuentes son escribir mal las mayúsculas en los matchers de los hooks, que la configuración sea sobrescrita por un settings.local.json de mayor prioridad, colocar .mcp.json en el directorio incorrecto, o escribir prohibiciones de seguridad en CLAUDE.md en lugar de usar reglas deny.

---

05 Rendimiento: lentitud, alto consumo de memoria y la búsqueda no encuentra archivos

La tercera categoría es cuando el sistema no funciona de forma fluida — las respuestas tardan cada vez más, la memoria se dispara o @file no autocompleta nada. La documentación oficial clasifica esto bajo "Rendimiento y estabilidad", y la mayoría de las veces se debe a un "contexto demasiado lleno" o a pequeños problemas del entorno, rara vez a un bug.

Analogía: si la computadora se vuelve lenta, suele ser porque hay demasiados programas abiertos en segundo plano, no porque el hardware esté dañado. No la llevarías a reparar de inmediato; primero cerrarías programas que consumen memoria y limpiarías la caché. Con la lentitud en Claude Code pasa lo mismo — organiza primero tu "mesa de trabajo" antes de pensar en reinstalar.

Lentitud / Alto consumo de memoria: organiza primero el contexto

El orden de acción que sugiere la documentación oficial es muy práctico:

1. Usa con frecuencia /compact para comprimir el contexto (organiza la conversación en un resumen de puntos clave, ver detalles en el Capítulo 19).
2. Cierra y reinicia Claude Code entre tareas principales.
3. Agrega directorios grandes de compilación al archivo .gitignore para evitar que se escaneen.

Si el consumo de memoria sigue siendo alto después de esto, puedes ejecutar /heapdump — esto generará una captura del montón (heap dump) de JavaScript en tu ~/Desktop (en Linux, si no hay escritorio, se escribirá en el directorio principal) que puedes adjuntar a un issue de GitHub al reportar problemas de memoria. No necesitarás este comando en el día a día, pero es bueno saber que existe.

Sobre quedarse congelado o girando indefinidamente: la documentación oficial es muy directa: presiona primero Ctrl+C para intentar cancelar la operación actual; si no hay respuesta en absoluto, cierra la terminal y reinicia. Reiniciar no perderá la conversación; puedes ejecutar claude --resume en el mismo directorio para continuar la sesión desde donde la dejaste.

El bucle de compresión automática (Autocompact thrashing): un error que asusta a los principiantes

Es posible que veas esta línea: Autocompact is thrashing: the context refilled to the limit.... No te preocupes — significa que la compresión automática tuvo éxito, pero un archivo muy grande o la salida de una herramienta volvió a llenar el contexto de inmediato, por lo que Claude Code detuvo los intentos para evitar consumir llamadas a la API en bucle. Solución: pide al modelo que lea el archivo grande en partes (especificando rangos de líneas o funciones concretas, en lugar de leer todo el archivo), o usa /compact indicando "mantener solo el plan y el diff", o bien limpia la sesión con /clear y comienza de nuevo.

Fallos en la búsqueda o en el autocompletado de @file: cambia el ripgrep

Si las herramientas de búsqueda, las menciones con @file o las skills personalizadas no encuentran archivos, es muy probable que el ripgrep integrado en Claude Code (una herramienta de búsqueda de alta velocidad) no pueda ejecutarse en tu sistema. La solución oficial es instalar la versión del sistema de ripgrep y configurar Claude Code para que la utilice:

# macOS
brew install ripgrep

Luego, define en tus variables de entorno USE_BUILTIN_RIPGREP=0 (para saber cómo configurar variables de entorno, consulta el Capítulo 42).

Aquí tienes una tabla de referencia rápida para problemas de rendimiento de tipo "síntoma → qué hacer primero":

Síntoma	Qué hacer primero
Cada vez más lento, alta memoria	Ejecuta /compact y luego reinicia Claude Code
Totalmente congelado, gira sin parar	Presiona Ctrl+C; si no funciona, cierra la terminal e inicia con claude --resume
Aparece Autocompact is thrashing	Pídele leer archivos grandes por partes + /compact keep only ...
Búsquedas o @file no encuentran archivos	Instala el ripgrep del sistema y define USE_BUILTIN_RIPGREP=0
Caracteres ilegibles o cuadros en la terminal integrada	Ejecuta /terminal-setup en Claude para desactivar el renderizado por GPU

La última situación, "caracteres ilegibles", ocurre ocasionalmente en la terminal integrada de VS Code, donde toda la pantalla se llena de cuadros de texto, lo cual resulta alarmante. Ejecutar /terminal-setup para desactivar la aceleración por GPU de la terminal y recargar la ventana suele solucionar el problema — es un fallo puramente visual del renderizado y no tiene relación con Claude.

💡 Resumen en una frase: Para problemas de rendimiento, sospecha primero de un "contexto saturado" — /compact + reiniciar es la solución universal; si se congela, presiona Ctrl+C / claude --resume; si la búsqueda falla, cambia al ripgrep del sistema; si hay caracteres extraños en la terminal, ejecuta /terminal-setup.

---

06 Errores de la API: si aparece texto en rojo, identifica primero "de quién es la culpa"

La cuarta categoría es cuando aparece directamente un mensaje en rojo del tipo API Error: ... en la sesión. Los principiantes suelen asustarse al ver el texto en rojo, pero lo que realmente se debe hacer es identificar si el error proviene "del servidor" o "de tu lado" — el manejo de ambas situaciones es completamente opuesto.

Analogía: si una página web no carga, primero averigua si el sitio está caído o si te quedaste sin internet. Si el sitio está caído, no servirá de nada actualizar la página cien veces; debes esperar a que lo reparen. Si te quedaste sin internet, entonces debes revisar tu router. Con los errores de la API se sigue la misma lógica: identifica a quién pertenece el problema y luego decide si debes "esperar" o "modificar".

Recuerda: Claude Code ya ha intentado reintentar automáticamente por ti

Vale la pena conocer este mecanismo incorporado: ante errores del servidor, sobrecargas, límites de tiempo, límites de tasa temporales o desconexiones, Claude Code reintentará automáticamente con un retraso exponencial hasta un máximo de 10 veces. Durante el reintento verás una cuenta atrás junto al icono de carga que dice Retrying in Ns · attempt x/y. Por lo tanto, cuando realmente ves una línea de error en pantalla, significa que ya se agotaron todos estos reintentos, no que la aplicación se haya rendido al primer fallo.

Tres categorías de errores y sus soluciones

He clasificado la extensa tabla oficial de errores en tres grupos clave que debes distinguir:

El error se ve así	De quién es la culpa	Qué debes hacer
API Error: 500 / 529 Overloaded / Server is temporarily limiting requests	Servidor (no es tu culpa)	Espera un momento antes de reintentar; revisa status.claude.com; cambia a otro modelo con /model (la capacidad se calcula por modelo)
You've hit your session/weekly/Opus limit	Tu límite de cuota se ha agotado	Espera al tiempo de restablecimiento; verifica la cuota con /usage; añade saldo o mejora tu plan con /usage-credits
Prompt is too long / Request too large	Tu solicitud es demasiado grande	Usa /compact o /clear; pide leer archivos muy grandes especificando la ruta y por partes, en lugar de pegar bloques enteros

La lógica para manejar estos tres grupos es completamente diferente: el primero consiste en "esperar", el segundo en "pagar o esperar al restablecimiento" y el tercero en "optimizar tu entrada". Si no los distingues, podrías hacer lo contrario — como borrar tu conversación cuando el servidor está inestable, o intentar reintentar indefinidamente cuando te has quedado sin saldo.

También está la categoría de no poder conectar con la API (Unable to connect to API, fetch failed, Request timed out junto con un texto de "comprobar red") — esto no suele ser culpa de Anthropic, sino de tu red local, VPN, proxy o firewall. El primer paso es verificar si puedes alcanzar el host de la API desde la misma terminal:

curl -I https://api.anthropic.com

Si conecta, significa que la red funciona y el problema está en un nivel superior (como el proxy o los certificados); si da Could not resolve host o expira el tiempo, entonces la red está bloqueada. Para los usuarios en regiones con restricciones, casi seguro requerirán configurar una VPN; en redes corporativas, a menudo se necesitará configurar HTTPS_PROXY. Si tienes una conexión lenta que causa desconexiones por límite de tiempo, puedes aumentar el tiempo de espera de una sola solicitud — la documentación oficial proporciona dos variables de entorno para esto (ver el Capítulo 42 para la configuración de variables de entorno):

Variable de entorno	Valor predeterminado	¿Para qué sirve?
API_TIMEOUT_MS	600000 (10 minutos)	Tiempo límite para una sola solicitud; auméntalo si usas redes lentas o proxies
CLAUDE_CODE_MAX_RETRIES	10	Cantidad de reintentos automáticos; redúcelo en scripts si deseas fallar rápido

Dos errores comunes para principiantes que suelen malinterpretarse

model not found / you may not have access to it: El nombre del modelo configurado no se reconoce o tu cuenta no tiene acceso. En la terminal interactiva, escribe /model para elegir uno de la lista de disponibles. Si el modelo incorrecto sigue apareciendo, significa que se configuró un ID de modelo obsoleto en alguna parte — revisa en orden de prioridad: el argumento --model → la variable de entorno ANTHROPIC_MODEL → settings.local.json → el campo model en los archivos settings.json, y borra el valor antiguo para que regrese al valor por defecto. La documentación oficial también recomienda: utilizar alias (como sonnet, opus) en lugar de IDs de versiones fijas, ya que los alias se actualizan automáticamente a la versión más reciente y no quedan obsoletos (ver el Capítulo 04 sobre Configuración de API para más detalles).

Claude Code is unable to respond to this request, which appears to violate our Usage Policy: Bloqueado por la política de uso. Ten en cuenta un detalle poco intuitivo: esta comprobación evalúa todo el historial de la conversación, no solo tu último mensaje, por lo que cambiar la redacción de la última frase a menudo volverá a dar el mismo error. Lo correcto es presionar Esc dos veces o usar /rewind para volver a la ronda previa a que se activara el bloqueo (ver detalles en el Capítulo 37), y cambiar el enfoque o la forma de expresarte; si no identifica qué ronda lo causó, limpia la sesión con /clear.

💡 Resumen en una frase: Para errores de la API, clasifícalos en tres grupos: 5xx/529 es culpa del servidor (esperar + revisar página de estado + cambiar modelo), hit your limit es de cuota (esperar restablecimiento o recargar saldo), y too long/too large es que tu entrada es demasiado grande (/compact / leer en partes); Unable to connect se debe a tu red (curl para verificar el host, configurar VPN o proxy si es necesario); para errores de modelo, prefiere alias y elimina IDs antiguos.

---

07 El arma secreta: logs de depuración --debug + método de comparación con configuración limpia

Las seis categorías anteriores cubren el 90% de los casos. Pero de vez en cuando te toparás con síntomas extraños que no se pueden localizar siguiendo la documentación. En esos momentos, recurre a estas dos herramientas avanzadas que te ayudarán a acorralar incluso el problema más complejo.

Analogía: para buscar un fallo eléctrico, usa un multímetro y desconecta componentes uno a uno. Cuando un electricista experto se topa con un fallo difícil de explicar, utiliza un multímetro para medir en tiempo real dónde no llega la corriente (ver logs en tiempo real) o va desconectando los aparatos uno a uno para ver con cuál de ellos desaparece el fallo (descarte progresivo). Estas dos herramientas secretas son exactamente el equivalente a esos métodos.

Arma 1: --debug para ver qué ocurre en tiempo real

Cuando no puedas deducir la causa solo con ver el resultado, inicia con --debug para ver los procesos internos en pantalla. Puedes añadir modificadores para ver únicamente la sección que te interesa:

Comando	Para verificar
claude --debug	Logs de depuración generales para ver el funcionamiento global
claude --debug mcp	Salida stderr del inicio y conexión de MCP servers (útil si el servidor conecta pero no muestra herramientas)
claude --debug hooks	Ver en tiempo real cada evento de hook, qué matchers coinciden, códigos de salida y resultados (útil si los hooks no se activan)

También cuentas con un comando dentro de la sesión, /debug [descripción del problema], que activa los logs de depuración para la sesión actual y le pide a Claude que use los logs y las rutas de configuración para ayudarte a diagnosticar.

Ejemplo de uso: configuraste un hook que aparece registrado en /hooks pero nunca se ejecuta — en este caso, inicia con claude --debug hooks y realiza una llamada a una herramienta. El log te mostrará claramente: "Llegó este evento, se comprobaron estos matchers y este fue el resultado". Esto es cien veces mejor que quedarse mirando fijamente la configuración.

Arma 2: método de comparación con configuración limpia (la técnica más subestimada)

Esta técnica es sumamente útil para resolver el misterio de si el problema está siendo causado por tu propia configuración. La idea es: iniciar una sesión limpia en la que no se cargue nada y compararla con tu sesión habitual. Si el problema desaparece en la sesión limpia, entonces la causa raíz está en algún lugar de tu configuración. El comando oficial:

cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

Esta instrucción apunta CLAUDE_CONFIG_DIR a un directorio vacío, evitando todo lo que se encuentre bajo ~/.claude; además, al ejecutarse desde un directorio sin carpetas .claude, archivos .mcp.json ni CLAUDE.md (como /tmp), se omiten también las configuraciones del proyecto. Esto da como resultado una sesión sin configuraciones de usuario o proyecto, hooks, MCP, plugins ni memoria.

• Si el problema desaparece en la sesión limpia → la causa raíz está en tu carpeta real ~/.claude o en el archivo .claude del proyecto. A partir de aquí, vuelve a agregar los elementos uno por uno (copia un archivo o inicia desde el directorio de tu proyecto) y observa cuál recrea el error: ese será el culpable.
• Si el problema persiste en la sesión limpia → entonces la causa raíz está fuera de las configuraciones de usuario y proyecto (puede deberse a configuraciones gestionadas, variables de entorno o un problema de instalación subyacente).

Este método de descarte es una sabiduría universal de resolución de problemas: reducir a la mitad las variables para ver si el fallo persiste. Por ejemplo, si Claude no lee una regla de CLAUDE.md por alguna razón, usar la sesión limpia te permitirá confirmar rápidamente: "No es un bug de Claude Code, sino que hay dos archivos CLAUDE.md en conflicto en el proyecto", ahorrándote una noche entera revisando documentación.

💡 Resumen en una frase: Ante problemas extraños, usa dos armas secretas: claude --debug [mcp/hooks] para ver logs internos en tiempo real e identificar por qué no funciona algo, y el método de comparación con configuración limpia (CLAUDE_CONFIG_DIR apuntando a un directorio vacío) para determinar si la culpa es de tu configuración, aplicando descarte para localizar al culpable.

---

08 Práctica: realiza un chequeo de salud completo a tu instalación

La teoría sin práctica se olvida. A continuación, realizaremos un chequeo de salud con /doctor y comprobaremos el estado de tu autenticación. Este proceso no requiere configuraciones complejas y se puede hacer tan pronto tengas instalado Claude Code.

Paso 1: Confirma en la terminal que claude esté bien instalado y actualizado

claude --version

Resultado esperado: se imprimirá una línea con la versión, por ejemplo, 2.1.xxx (Claude Code). Ver el número de versión = instalación básicamente saludable. Si obtienes command not found: claude, significa que el directorio de instalación no está en tu PATH; esto es un problema de instalación, regresa al Capítulo 02 para reparar el PATH según tu plataforma (en macOS/Linux, la instalación local está en ~/.local/bin).

Paso 2: Entra a la sesión y realiza el chequeo

claude

Una vez dentro, escribe:

/doctor

Resultado esperado: se abrirá un panel de diagnóstico que detalla el estado de la instalación, la validez de los archivos de configuración (los parámetros inválidos o errores de esquema se resaltarán en rojo), los servidores MCP y el uso de contexto. Si no hay errores en ningún apartado, tu configuración está completamente limpia. Si se detecta un problema, presiona f para enviar el informe a Claude y dejar que te ayude a resolverlo paso a paso.

Paso 3: Confirma qué credenciales se están utilizando actualmente

A continuación, escribe:

/status

Resultado esperado: se mostrará el método de autenticación activo actual. Si eres un usuario con suscripción, aquí debería mostrarse OAuth (suscripción) y no una API key. Si ves que se está usando una API key y no coincide con lo que esperabas, felicidades: has detectado a tiempo la trampa clásica. Ve a tu archivo de configuración de shell, ejecuta unset ANTHROPIC_API_KEY y borra la línea export correspondiente.

Paso 4 (Opcional): Experimenta una comparación con configuración limpia

Para probar la técnica explicada en la Sección 07, inicia una sesión limpia en la que no se cargue nada:

cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

Resultado esperado: tras iniciar, esta sesión no incluirá ninguno de tus archivos CLAUDE.md, comandos personalizados ni MCP servers habituales (si escribes /memory o /mcp verás que están vacíos). Esta será tu base de comparación en el futuro para determinar si tus configuraciones están causando problemas. Nota: en Linux y Windows esto te pedirá iniciar sesión de nuevo (las credenciales se guardan en el directorio de configuración), mientras que en macOS se importarán automáticamente del Keychain. Al terminar, sal de la aplicación de forma normal; este directorio temporal no afectará tu carpeta real ~/.claude.

Al completar estos cuatro pasos, habrás recorrido la ruta principal de diagnóstico: "chequeo → verificar credenciales → iniciar sesión limpia para comparar". Si tienes problemas en el futuro, sigue este orden en lugar de probar cosas al azar.

💡 Resumen en una frase: Realiza el recorrido de diagnóstico: claude --version → /doctor → /status → sesión limpia; recuerda que /doctor señala la dirección y /status verifica las credenciales, con lo que resolverás la gran mayoría de problemas de principiantes de inmediato.

---

09 Resumen

Este capítulo te ha proporcionado un marco de trabajo estructurado y lógico para la resolución de problemas, desde clasificar el tipo de fallo hasta elegir el comando adecuado, además de dos armas secretas para los problemas más complejos.

Repasemos los puntos clave:

Tu situación	Acción de resolución	Concepto clave
No sabes a qué categoría pertenece el problema	Tabla de enrutamiento + /doctor	Clasifica primero y luego actúa, no pruebes al azar
Petición repetida de login / organización desactivada	/status para verificar credenciales	Suele ser que una variable ANTHROPIC_API_KEY residual se impone a la suscripción
Opciones / hooks / MCP no surten efecto	/context, /hooks, /mcp	Verifica "qué se ha cargado realmente"; cuidado con mayúsculas y sobrescrituras
Lentitud / alta memoria / fallos de búsqueda	/compact + reiniciar / cambiar ripgrep	Suele ser un contexto saturado o pequeños detalles del entorno
Mensaje de error de la API en rojo	Clasifica en "servidor", "cuota" o "solicitud"	5xx requiere ver la página de estado, limit requiere restablecer o recargar, too long requiere resumir
No puedes localizar la causa de un fallo extraño	--debug + comparación limpia	Ver logs en tiempo real + descarte para reducir variables

Ahora estás preparado para: no asustarte ante los errores de Claude Code. Usa la tabla de enrutamiento para clasificar la categoría del problema, ejecuta /doctor para diagnosticar la dirección y /status para comprobar las credenciales; actúa según la categoría (instalación, autenticación, configuración, rendimiento, errores); para fallos complejos, usa --debug para ver logs o inicia una sesión limpia para descartar por mitades; y si no hay forma de solucionarlo, reporta con /feedback. Convierte este proceso en tu hábito de resolución de problemas para pasar de asustarte ante un error a saber exactamente en qué dirección investigar.

Ahora que has aprendido desde instalar y usar hasta resolver problemas de tu entorno, es momento de definir con precisión los términos que han ido apareciendo en el camino.

---

Próximo capítulo

El próximo capítulo es 52 "Glosario (para principiantes)" — a lo largo de esta guía han aparecido docenas de términos como CLAUDE.md, ventana de contexto, MCP, Sub-agent, Hook, checkpoint, auto-compact... En el próximo capítulo te ofrecemos un glosario adaptado para principiantes: cada término explicado en una frase sencilla, acompañado de una analogía y organizado por temas para que lo puedas consultar en cualquier momento y entender de inmediato. Piensa en esto: si alguien te pregunta de repente "¿qué relación hay entre un token y la ventana de contexto?", ¿sabrías explicárselo de forma sencilla ahora mismo?

---

Lecturas recomendadas

• Comandos de barra diagonal (Slash Commands): un / para acceder a todos los accesos rápidos de Claude
• Configuración de desarrollo: ajusta el "entorno de trabajo" para Claude
• Cuatro flujos de trabajo comunes: explorar el código, corregir bugs, refactorizar y escribir pruebas