Si Claude Code muestra que el proceso terminó con code 1, no empieces por reinstalar, borrar toda la configuración o cambiar credenciales. El mensaje solo dice que el proceso lanzado por Claude Code terminó con un código genérico de fallo. Todavía no sabes si el dueño es el terminal, VS Code, Cursor, Claude Desktop, un wrapper, auth, PATH, una sesión antigua, una actualización o el estado del servicio.
Empieza por el tablero de ramas
Las discusiones en español mezclan respuestas de Reddit, issues de GitHub, vídeos, documentación oficial y consejos sobre auto-attach, Node, caché y ~/.claude. Eso confirma que la necesidad es reparar rápido, pero también muestra el riesgo: una solución única puede arreglar una rama y romper otra.
| Condición visible | Primera rama | Primer movimiento seguro | Verificación en la misma ruta | Escala cuando |
|---|---|---|---|---|
| Falla en un terminal normal | Terminal o instalación | Abre un shell nuevo en la misma carpeta y ejecuta claude doctor | Repite el mismo comando | El nuevo shell conserva el fallo |
| Solo falla dentro de VS Code, Cursor o un IDE | Subproceso IDE | Ejecuta el mismo comando en el terminal del sistema | Compara IDE contra raw terminal | Raw terminal funciona e IDE falla |
| Empezó tras login, cambio de cuenta o API key | Auth o sesión | Revisa /status y refresca solo esa ruta | Repite el mismo login path | Status normal, misma ruta falla |
| Windows, shell, Git o PATH no encuentran el binario | PATH e instalación | Revisa where claude, Git y PATH | Nuevo terminal ve el binario correcto | Prerrequisitos pasan, inicio falla |
| Falla vía npm, hook, alias, CI o task runner | Wrapper o script | Omite el wrapper y ejecuta claude directo | Reintroduce capas una por una | Direct path funciona, wrapper falla |
| Solo falla un workspace o conversación antigua | Estado de sesión | Crea una sesión mínima nueva | Ejecuta una tarea mínima equivalente | La sesión nueva también falla |
| Empezó justo después de una versión o incidente | Versión o estado | Registra versión y hora del status check | Repite la misma ruta después | El paquete de evidencia está limpio |
El tablero no es una lista de trucos. Es una forma de proteger la señal. Si reinstalas, limpias caché, cambias PATH, rotas tokens y desactivas extensiones a la vez, quizá recuperes el sistema, pero perderás la causa. La recuperación real se mide en la ruta original: si fallaba en VS Code, debe volver a funcionar en VS Code; si fallaba en npm script, debe volver a funcionar en ese script.
Qué significa el error
Esa señal de code 1 significa que un proceso terminó con fallo general. Puede pasar antes de una llamada API, antes de un request id, dentro de un subproceso lanzado por el IDE, después de un hook, al leer configuración, durante auth refresh, por timeout de un wrapper o durante degradación del servicio.
Por eso las respuestas únicas son frágiles. Desactivar auto-attach en VS Code puede ser correcto para una rama. Borrar caché y archivos de ~/.claude puede servir para una sesión dañada. Actualizar Node puede tener sentido si el entorno apunta ahí. Pero si el problema era un token, un wrapper o un incidente, esos cambios añaden ruido.
La regla operativa es: fija la superficie, cambia una sola variable, verifica la misma superficie, guarda evidencia si sigue fallando. Esa regla evita que una reparación temporal se convierta en una máquina difícil de explicar.
Estado, autenticación y login
Usa esta rama si el fallo apareció cerca de login, SSO, cambio de cuenta, transición entre subscription y API key, OAuth, permisos de organización o un incidente visible. Status y auth son ramas distintas: un incidente pide conservar estado local y reintentar más tarde; auth pide inspeccionar la ruta activa.
Primero revisa el estado actual y registra la hora. Si Claude Code acepta slash commands, usa /status para ver la cuenta y la ruta activa. Si la causa parece login, refresca solo esa ruta: logout/login, OAuth o el comando documentado correspondiente. No rotes todas las claves y no borres todo ~/.claude sin haber aislado la rama.
Si la evidencia se convierte en HTTP 500, server error o request id, usa la guía de Claude Code API Error 500. Si el problema es confusión entre API key y subscription billing, ve a Claude Code API key vs subscription. Si aparece usage window o explicit limit, es otra página.
Windows, PATH e instalación
La rama de instalación solo debe ser primera cuando hay señales de command not found, binario equivocado, Git ausente, shell no compatible, permission error o primer arranque roto. El mensaje code 1 por sí solo no prueba instalación dañada.
En macOS/Linux revisa claude --version, which claude y claude doctor. En Windows revisa where claude, git --version, PowerShell/WSL y el orden de PATH. Si un terminal nuevo no puede obtener la versión, estás en instalación. Si la versión funciona pero solo falla dentro de un IDE, proyecto o script, mira IDE, entorno, sesión o wrapper.
Si aún no tienes los prerrequisitos claros, la guía de instalación de Claude Code es la ruta correcta. Este artículo empieza cuando Claude Code ya existe y una superficie concreta lo ve terminar con code 1.
IDE, entorno y sesión
Esta rama es crítica porque los casos en español repiten el patrón VS Code auto-attach como una causa fuerte, pero no universal. Un IDE puede inyectar variables, cambiar working directory, alterar shell, ejecutar launch tasks, activar debugger auto-attach o cargar extensions que no existen en el terminal del sistema.
Haz una comparación cruda. En un terminal del sistema entra al mismo proyecto y ejecuta pwd, claude --version y un arranque mínimo de claude. Luego repite desde el IDE con el mismo directorio y comando. Si el terminal funciona y el IDE falla, mira extension output, integrated terminal shell, workspace settings, launch/task config, debugger auto-attach, injected env y working directory.
Si ambos fallan, mira entorno y sesión. Inspecciona solo lo que puede afectar el arranque: PATH, proxy, token/auth variables, shell startup, Node shim, red corporativa. No imprimas secrets ni los borres. Para session state, crea una carpeta temporal o una sesión mínima y ejecuta una tarea pequeña. Si funciona, la sesión vieja o el workspace forman parte del problema.
Hooks, wrappers y CI
Un wrapper puede devolver code 1 y hacer que parezca que Claude Code falló. Esto pasa con npm scripts, aliases, shell functions, pre-commit hooks, CI steps, task runners y capas de timeout.
Primero ejecuta claude directo desde un terminal limpio. Si funciona, reintroduce una capa cada vez: alias, npm script, hook, CI, timeout wrapper. La primera capa que recupera el fallo es el dueño inicial. Revisa exit code, permisos, working directory, environment, timeout y redirección de logs.
Si el direct command funciona, reinstalar Claude Code cambia una capa que ya está bien. En CI revisa también secrets, permisos del job, ubicación del checkout, shell no interactivo y timeout. No conviertas un problema de wrapper en una supuesta caída global de Claude Code.
Actualización, regression o incidente vivo
La rama de versión/estado es real, pero debe basarse en evidencia actual. Registra claude --version, ruta de instalación, sistema operativo, shell, versión de extensión IDE, resultado en raw terminal, hora del status check y cambios recientes.
Si el mismo camino se recupera cuando termina un incidente, era una rama de servicio. Si solo ocurre en una versión y desaparece tras un fix o rollback, era rama de versión. Si ninguna de esas cosas es cierta, no sigas usando "la última actualización" como explicación permanente.
Esta rama evita churn local. Durante un incidente, limpiar caché, rotar claves y reinstalar puede dejar el entorno peor. Durante una regression, abrir un issue sin versión ni superficie de inicio obliga al mantenedor a empezar desde cero.
Verificación de la misma ruta y paquete de evidencia
La reparación no termina cuando una ruta distinta funciona. Si el fallo original fue en VS Code, el raw terminal exitoso solo clasifica. Si el fallo original fue en npm script, el direct command exitoso apunta al wrapper. Todavía debes volver a la ruta que fallaba.
Antes de escalar, prepara un paquete corto: comando o launch path exacto, texto completo del error, versión de Claude Code, sistema operativo, shell, IDE, hora de status check, ruta de auth activa, cambios recientes, comparación raw terminal vs IDE o wrapper, pasos mínimos, logs, session id, request id o correlation id si existe. Si no hay request id, dilo: puede indicar que el proceso murió antes de llegar a la API.
Un reporte útil dice: "Windows, VS Code, version X, raw terminal works, IDE fails, disabling auto-attach recovers the same IDE path". Un reporte débil dice: "process exited with code 1". La diferencia está en la rama, no en la longitud.
Acciones rápidas por rama
| Rama | Haz primero | Evita primero | Evidencia de éxito |
|---|---|---|---|
| Terminal | Shell nuevo, misma carpeta, claude doctor | Borrar toda config | Mismo comando arranca |
| Auth/sesión | /status, refresh puntual | Rotar todos los tokens | Mismo login path funciona |
| Windows/PATH | where claude, Git, PATH | Reinstalar sin evidencia | Nuevo terminal ve el binario |
| IDE | Comparación con terminal del sistema | Culpar a Claude Code globalmente | IDE path coincide con terminal |
| Entorno | PATH/proxy/token/shell startup | Imprimir o borrar secrets | Una diferencia explica el fallo |
| Wrapper | Omitir wrapper y devolver capas | Cambiar Claude Code primero | Direct path funciona, wrapper aislado |
| Estado/versión | Hora de status y version | Usar posts antiguos como prueba actual | Misma ruta se recupera tras evento |
| Desconocido | Paquete de evidencia | Fixes aleatorios | Issue incluye notas de rama |
Preguntas frecuentes
¿Significa que Claude Code está caído?
No por sí solo. Revisa status, pero mantenlo como una rama. Terminal local, IDE, wrapper, auth, session y PATH pueden mostrar el mismo mensaje.
¿Debo reinstalar primero?
Normalmente no. Reinstala solo cuando la rama de instalación tiene evidencia: binario ausente, PATH roto, Git/shell faltante, permisos o instalación corrupta.
¿Cuál es la comprobación segura más rápida?
Fija la superficie de inicio y compara la ruta fallida contra el terminal del sistema. Luego cambia una sola cosa y repite la misma ruta.
¿Qué hago si solo falla en VS Code o Cursor?
Ejecuta el mismo comando en la misma carpeta fuera del IDE. Si funciona, revisa extension logs, integrated shell, workspace settings, auto-attach, env variables y working directory.
¿Es lo mismo que API 500 o rate limit?
No. Process exit puede ocurrir antes de la API. Si tienes HTTP 500 o request id, usa la guía API Error 500. Si la evidencia apunta a usage limits, usa la guía de Claude Code rate limit.
Regla de trabajo
Trata Claude Code exit code 1 como un problema de routing. Identifica la superficie de inicio, prueba la rama menos destructiva, cambia una sola variable, verifica la misma ruta y escala solo cuando el mismo camino sigue fallando con evidencia limpia.