Índice
- 1. Los «comandos de diagnóstico» que conviene ejecutar primero
- 2. Autenticación e inicio de sesión
- 3. Uso y límites de tasa (lo más común)
- 4. Contexto y tokens
- 5. Servidor y modelo
- 6. Instalación, PATH y actualización
- 7. Red y proxy
- 8. MCP (servidores conectados)
- 9. Permisos y herramientas
- 10. Otros (thinking / imagen-PDF / IDE)
- 11. Chuleta de error → solución
- Resumen
- Preguntas frecuentes
Estás trabajando en Claude Code y de repente se detiene con un error: «vuelve a iniciar sesión», «límite de tasa», «el prompt es demasiado largo», «MCP no conecta». Hay tantos tipos que buscar cada uno en Google acaba siendo tedioso. Este artículo es una referencia práctica que cataloga los errores que verás con más frecuencia en Claude Code, con la causa y el comando que debes ejecutar para cada uno.
Lo esencial primero: para la mayoría de los errores, ejecutar antes que nada claude doctor (diagnóstico completo), /status (tu autenticación actual) y /context (desglose del contexto) acotará la causa. Y los casos comunes se agrupan en cuatro familias: ① uso/límites de tasa, ② desbordamiento de contexto, ③ autenticación caducada, ④ fallos de conexión de MCP. A continuación, cada categoría se organiza como «síntoma → causa → comando de solución». Guárdalo en favoritos y salta a la sección pertinente cuando te atasques.
Ante la duda, estos 3 comandos
— casi todos los errores empiezan por aislar la causa
Las cuatro familias: ① uso/límites de tasa ② desbordamiento de contexto ③ autenticación caducada ④ fallo de conexión de MCP.
Y, sin hacer ruido, «actualizar a la última versión» claude update resuelve muchos errores.
* Los comandos y soluciones aquí se basan en la documentación oficial de Claude Code (a fecha de 2026). Claude Code se actualiza rápido, y los nombres de los comandos y la redacción de los mensajes pueden cambiar. Confirma lo más reciente con claude doctor y la documentación oficial.
1. Los «comandos de diagnóstico» que conviene ejecutar primero
Antes de meterte en errores concretos, conocer los comandos de diagnóstico que ayudan a aislar la causa te permite identificar la mayoría de los problemas con rapidez.
| Comando | Qué muestra / hace |
|---|---|
claude doctor | Comprobación completa de la instalación, los ajustes, los servidores MCP y el uso del contexto |
/status | El método de autenticación actualmente activo (Pro / Max / Team / clave API) |
/context | Desglose del contexto (prompt del sistema, historial, archivos, herramientas MCP) |
/usage | Límites del plan actual y horas de reinicio |
/permissions | Lista de reglas de permisos (permitir/denegar) y sus orígenes |
/mcp | Estado de conexión de los servidores MCP y número de herramientas expuestas |
/feedback | Reportar un error a Anthropic junto con el registro de la conversación |
2. Autenticación e inicio de sesión
La familia del «funcionaba y de repente me pide iniciar sesión». La trampa clásica es una clave API en una variable de entorno que anula tu suscripción.
| Síntoma | Causa | Solución |
|---|---|---|
| Not logged in / Please run /login (no has iniciado sesión) | Sin credencial válida (token caducado, etc.) | /login. Si se repite, revisa el reloj del sistema y el bloqueo del Keychain |
| Invalid API key (clave API no válida) | Persiste una ANTHROPIC_API_KEY obsoleta | env | grep ANTHROPIC → unset ANTHROPIC_API_KEY → /login |
| OAuth token revoked / expired (token OAuth revocado/caducado) | Sesión cerrada en otro lugar / desactivada por un administrador | /logout → /login. Sospecha también de un desfase del reloj |
| This organization has been disabled (organización desactivada) | Una clave API de una organización desactivada tiene prioridad | Elimina la clave del perfil del shell (.zshrc, etc.) → /login → confirma con /status |
| 403 Forbidden (after login) | Suscripción caducada / rol ausente / interferencia del proxy | Revisa la suscripción y el rol en la Console. Para proxies, define HTTPS_PROXY |
Regla general: una clave API en una variable de entorno tiene prioridad sobre el inicio de sesión por suscripción. Si definiste ANTHROPIC_API_KEY para una tarea de CI y la olvidaste, tu plan personal Pro/Max queda ignorado. Comprobar primero «qué credencial está activa» con /status es lo más acertado.
3. Uso y límites de tasa (lo más común)
La queja más habitual con Claude Code. Claude Code consume entre 10 y 100 veces más tokens que el chat (conversaciones de varios turnos, contextos enormes, idas y vueltas de herramientas), así que alcanzas los límites más rápido de lo que parece.
3 movimientos cuando «alcanzas el límite»
/usage para los límites y la hora de reinicio, /status para la credencial/model para un modelo más ligero, /compact para reducir el historial, desactiva los MCP que no uses
Nota: «Server is temporarily limiting requests» (el servidor está limitando las solicitudes temporalmente) es una restricción breve del lado del servidor, no el límite de tu plan. Solo espera y reintenta.
No lo confundas con los límites del plan (por sesión/semanales).
Más: «429 / Request rejected» es una superación de tasa en tu clave API o espacio de trabajo. «Credit balance is too low» es el saldo prepago de la Console agotado (recárgalo en facturación o pásate a una suscripción). Ten en cuenta que, hacia marzo de 2026, usuarios de Max reportaron que sus ventanas de 5 horas se agotaban anormalmente rápido en medios técnicos y en las issues del repositorio oficial (sospecha de bug). Si te vuelve a ocurrir, actualiza a la última versión, mide con /usage y envía /feedback si hace falta. Para ahorrar tokens de forma sistemática, consulta ahorro de tokens en IA y ahorro de tokens en Claude Code.
4. Contexto y tokens
Esto aparece cuando manejas reuniones largas o archivos enormes.
| Síntoma | Causa | Solución |
|---|---|---|
| Prompt is too long (el prompt es demasiado largo) | La conversación + los archivos superan la ventana de contexto | /compact (resumir), /clear (reiniciar), /context para ver el desglose, desactivar los MCP que no uses con /mcp |
| Error during compaction: Conversation too long (error durante la compactación: conversación demasiado larga) | No hay espacio libre suficiente para la salida de la compactación | Esc dos veces para retroceder unos turnos y luego /compact. Si sigues atascado, /clear |
| Auto-compact is thrashing (la autocompactación entra en bucle) | Una salida enorme vuelve a llenar el contexto justo tras la compactación | Lee los archivos grandes por rango de líneas / /compact keep only <focus> / pásalo a un subagente |
El truco es no leer nunca un archivo enorme entero. Pasa registros y datos en trozos pequeños por rango de líneas. Entender la idea de la ventana de contexto hace que esta clase de error sea mucho más rara.
5. Servidor y modelo
| Síntoma | Causa | Solución |
|---|---|---|
| 500 Internal server error | Fallo temporal del lado de Anthropic | Revisa status.claude.com → reintenta tras 1 min |
| 529 Overloaded (repeated) (sobrecargado, repetido) | La API está temporalmente al límite de capacidad | Espera unos minutos. Cambia de modelo con /model para repartir la carga |
| Request timed out (se agotó el tiempo de la solicitud) | Sin respuesta dentro del límite de 10 min por defecto | Divide la tarea. En una línea lenta, sube API_TIMEOUT_MS |
| model not found / no access (modelo no encontrado / sin acceso) | Nombre de modelo incorrecto o no incluido en tu plan | /model para reseleccionar. Revisa una ANTHROPIC_MODEL obsoleta en las variables de entorno |
| Opus is not available with Pro plan (Opus no está disponible con el plan Pro) | El modelo seleccionado no está en tu plan | /model a uno disponible. Tras un cambio de plan, /logout→/login |
6. Instalación, PATH y actualización
| Síntoma | Causa | Solución |
|---|---|---|
| command not found: claude | El directorio de instalación no está en el PATH | Añade ~/.local/bin (Win: %USERPROFILE%\.local\bin) al PATH |
| Install fails (HTML error, etc.) (la instalación falla) | Bloqueo por proxy / región | Homebrew brew install --cask claude-code / WinGet winget install Anthropic.ClaudeCode |
| TLS / SSL certificate verification failed (fallo de verificación del certificado) | Inspección TLS del proxy corporativo / CA ausente | Apunta NODE_EXTRA_CA_CERTS=/path/ca.pem. NUNCA definas NODE_TLS_REJECT_UNAUTHORIZED=0 |
| Multiple claude installations found (varias instalaciones de claude) | Duplicados de npm/Homebrew/nativo | Conserva una, p. ej. npm uninstall -g @anthropic-ai/claude-code |
| Bugs from an old version (errores de una versión antigua) | Sin actualizar | claude update (la solución estrella que resuelve muchos errores) |
7. Red y proxy
Habitual en redes corporativas y VPN. Confirma primero la accesibilidad con curl -I https://api.anthropic.com.
| Síntoma | Causa | Solución |
|---|---|---|
| Unable to connect / ECONNREFUSED / ETIMEDOUT | Sin conexión / bloqueo de VPN / proxy sin configurar | Define HTTPS_PROXY=http://proxy:8080. Pide a TI que permita api.anthropic.com |
| SSL certificate verification failed (corporate) | Certificado de interceptación autofirmado | Obtén el paquete de CA de TI y define NODE_EXTRA_CA_CERTS |
| 403 host_not_allowed (cloud runs) | Fuera de la lista de permitidos del entorno en la nube | Configura el acceso de red como Custom y permite el dominio de destino |
8. MCP (servidores conectados)
Te topas con estos en cuanto empiezas a usar servidores MCP. Comprueba primero el estado con /mcp.
| Síntoma | Causa | Solución |
|---|---|---|
| Server failed to connect / Pending approval (el servidor no conectó / aprobación pendiente) | El servidor se cayó / inaccesible / requiere autenticación | /mcp para ver el estado. stdio: comprueba que el comando exista y sea ejecutable; HTTP: revisa la URL/las cabeceras de autenticación |
| Tool not found (herramienta no encontrada) | Conectado pero sin herramientas expuestas / nombre incorrecto | /mcp para confirmar el número de herramientas, claude mcp get <name> para su estado |
| Reconnection attempts exhausted (intentos de reconexión agotados) | Servidor HTTP/SSE caído tras 5 reintentos | Confirma que el servidor está activo, reconexión manual en /mcp. Para stdio, reinicia claude |
| MCP server timeout (tiempo de espera del servidor MCP agotado) | Arranque >5s, etc. | MCP_TIMEOUT=10000 claude (ms). Por servidor: "timeout" en .mcp.json |
9. Permisos y herramientas
La familia del «me pidió permiso incluso en modo bypass». El punto clave: las reglas de denegación tienen prioridad sobre las de permitir y sobre bypass.
| Síntoma | Causa | Solución |
|---|---|---|
| Asked for permission even in bypass mode (pide permiso incluso en modo bypass) | Las reglas de denegación ganan; las operaciones peligrosas siempre preguntan (cortafuegos) | Revisa y ajusta las reglas de denegación en /permissions |
| Tool execution denied by PreToolUse hook (ejecución de herramienta denegada por un hook PreToolUse) | Un hook lo bloqueó con el código de salida 2 | Revisa el hook en .claude/settings.json. Ve la salida con claude --debug |
Para entender por qué el bypass aún se detiene, consulta por qué pide permiso incluso en modo bypass; para un diseño seguro de permisos, consulta modos de permisos y seguridad.
10. Otros (thinking / imagen-PDF / IDE)
- thinking blocks cannot be modified (400) (los bloques de pensamiento no se pueden modificar): un bug conocido en el que los bloques de extended thinking se corrompen en el historial. Esc dos veces → /rewind, o si no una sesión nueva, y
claude update. Detalles: error 400 de thinking blocks. - Could not check the pull request status (no se pudo comprobar el estado del pull request): un problema de conexión con GitHub (a menudo de autenticación de
gh). Empieza congh auth status. Detalles: error de estado del PR. - Image was too large / PDF too large (imagen demasiado grande / PDF demasiado grande): las imágenes de más de 8000px en el lado más largo y los PDF de más de 100 páginas / 32 MB se rechazan. Esc dos veces para quitar el adjunto; redimensiona o lee por rango de líneas. Referencia los archivos grandes por su ruta en lugar de pegarlos.
- VS Code extension won't connect (la extensión de VS Code no conecta): confirma que
claude --versionfunciona en la terminal de VS Code. Revisa el PATH, reinicia VS Code y reinstala la extensión.
11. Chuleta de error → solución
| Cuando ocurre esto | Prueba esto primero |
|---|---|
| Causa desconocida / general | claude doctor → /status → /context |
| De repente te pide iniciar sesión | /status → (si hay una clave obsoleta) unset ANTHROPIC_API_KEY → /login |
| Alcanzaste un límite de tasa | /usage → /model más ligero → /compact → espera |
| Prompt is too long | /compact → /clear → lee los archivos grandes por rango de líneas |
| 500/529/timeout | Revisa status.claude.com → espera un poco → /model |
| command not found: claude | Añade ~/.local/bin al PATH |
| No conecta (red corporativa) | curl -I https://api.anthropic.com → HTTPS_PROXY/NODE_EXTRA_CA_CERTS |
| MCP no conecta | /mcp → revisa URL/permisos/comando → MCP_TIMEOUT |
| Pide permiso incluso en bypass | /permissions para revisar las reglas de denegación |
| Solo quieres que se arregle | claude update (la última versión arregla muchas cosas) |
Resumen
Claude Code tiene muchos errores, pero el primer movimiento es aislar la causa con tres comandos: claude doctor / /status / /context, y eso pone en marcha de nuevo casi todos los problemas. Los comunes son cuatro familias —uso/límites de tasa, desbordamiento de contexto, autenticación caducada, fallo de conexión de MCP— con /usage, /compact, /login y /mcp como soluciones de primera línea.
Y el movimiento más fuerte y fácil de pasar por alto es mantenerlo al día con claude update. Claude Code se actualiza rápido, y los errores pasados (como el 400 de thinking blocks) a menudo desaparecen solo con subir la versión. «Cuando te atasques, primero los tres comandos de diagnóstico; si no se arregla, actualiza a la última versión.» Mantén ese patrón y dejarás de fundir tu tiempo en errores.
Lectura relacionada: error 400 de thinking blocks, error de comprobación del estado del PR, ahorro de tokens en Claude Code, por qué pide permiso en modo bypass y qué es MCP.
Preguntas frecuentes
P. Apareció un error: ¿qué hago primero?
R. Ejecuta claude doctor. Comprueba la instalación, los ajustes, MCP y el contexto de una sola vez. Después mira /status (autenticación actual) y /context (qué se come el contexto), y normalmente podrás distinguir si es un problema de autenticación, de contexto o de conexión.
P. Alcanzo los límites de tasa enseguida. ¿Qué ayuda?
R. Claude Code consume entre 10 y 100 veces más tokens que el chat, así que los alcanzas antes de lo esperado. Comprueba los límites y la hora de reinicio con /usage, cambia a un modelo más ligero con /model, reduce el historial con /compact y desactiva los MCP que no uses. Si no basta, valora un plan superior (Max, etc.) o créditos adicionales.
P. Dice «Invalid API key» pero mi clave debería ser correcta.
R. La causa clásica es una variable de entorno ANTHROPIC_API_KEY obsoleta que anula tu suscripción. Compruébalo con env | grep ANTHROPIC, unset ANTHROPIC_API_KEY (elimínala también de tu perfil del shell), luego /login y confirma con /status.
P. No conecta en mi red corporativa.
R. Confirma primero la accesibilidad con curl -I https://api.anthropic.com. Para un proxy, define HTTPS_PROXY; para la inspección TLS, apunta NODE_EXTRA_CA_CERTS al certificado de la CA. No uses NODE_TLS_REJECT_UNAUTHORIZED=0: es peligroso. La vía correcta es pedir a TI que permita api.anthropic.com.
P. Nada de lo que pruebo funciona: ¿último recurso?
R. Actualiza a la última versión con claude update. Claude Code se actualiza rápido y los errores conocidos a menudo desaparecen solo con subir la versión. Si sigue fallando, repórtalo con /feedback (incluye el registro de la conversación) a Anthropic.
