Failed to refresh OAuth token en Claude Code: el bloqueo de 60 s

Si Claude Code se detiene con Failed to refresh OAuth token: another Claude Code process is refreshing it or exited mid-refresh (así sale en claude -p y en el Agent SDK) o con Could not refresh your login because another Claude Code process is refreshing it (en una sesión interactiva), tu inicio de sesión no ha sido rechazado. Según la documentación de errores de Claude Code, la sesión guardada había caducado y tocaba renovarla, pero otro proceso de Claude Code en el mismo equipo tenía el bloqueo de renovación, o terminó y lo dejó puesto, y Claude Code paró la petición antes de enviarla. Ese bloqueo es, físicamente, una carpeta vacía: ~/.claude/.oauth_refresh.lock.

Lo primero es reintentar pasado un minuto. Un bloqueo que nadie actualiza caduca 60 s después de su última actualización y el siguiente intento lo retira solo; así se comportó Claude Code 2.1.316 en una prueba hecha en un Mac el 12 de noviembre de 2026. Si el mensaje vuelve, cierra el otro proceso de Claude Code (otra ventana de VS Code, Claude in Chrome, un script). Si ya no queda ninguno y la carpeta sigue ahí, bórrala con rmdir ~/.claude/.oauth_refresh.lock, y deja /login para el final: volver a iniciar sesión no espera al bloqueo.

Hay dos casos en los que esperar no sirve: cuando el reloj del equipo saltó hacia atrás y la carpeta quedó con una fecha futura, y en Windows, donde hay reportes de carpetas abandonadas que no se liberaban ni a los tres minutos. En los dos, lo que lo resuelve es borrar esa carpeta vacía. Lo que no debes borrar es .credentials.json ni la entrada del Llavero: ahí está la sesión que todavía es válida.

Qué es el bloqueo: dos carpetas vacías y un archivo junto a ~/.claude

El bloqueo existe para que dos sesiones no renueven el mismo token a la vez. La guía oficial de solución de problemas de instalación de Claude Code lo explica así: las sesiones en paralelo en un mismo equipo comparten la sesión guardada y coordinan su renovación para que solo un proceso renueve el token cada vez. Esa coordinación se hace con tres elementos en disco, que aparecieron mientras Claude Code 2.1.316 renovaba la sesión en la prueba del 12 de noviembre de 2026 (Mac, credenciales falsas en una carpeta de configuración aislada con CLAUDE_CONFIG_DIR, sin tocar ninguna sesión real) y desaparecieron al terminar el proceso:

El archivo owner tiene esta forma (los valores entre <> cambian en cada equipo):

{"pid": <número de proceso>, "procStart": "<hora de inicio del proceso>", "pidDomain": "darwin", "pidSpace": "<nombre del equipo>", "lockBirthtimeMs": <milisegundos>, "legacyLockBirthtimeMs": <milisegundos>}

Si usas CLAUDE_CONFIG_DIR, todo se mueve a esa carpeta: el bloqueo y el archivo owner quedan dentro de ella, y el bloqueo antiguo es esa misma ruta terminada en .lock.

Las dos formas del mensaje, y también la de disco lleno, están tal cual en los ejecutables de Claude Code 2.1.312, 2.1.314 y 2.1.316 para Mac (arm64), según una búsqueda en esos binarios hecha el 12 de noviembre de 2026. Las reglas del bloqueo, leídas en el código de la 2.1.316, son pocas. El proceso que renueva actualiza la fecha de la carpeta cada 5 s; una carpeta con más de 60 s sin actualizar se considera abandonada y se puede borrar. El proceso que espera reintenta cinco veces con pausas aleatorias de 1–2 s y después mira durante 7,5 s si la fecha se mueve. En la prueba, el mensaje tardó unos 8 s en aparecer (7,9, 8,0 y 8,6 s en tres intentos) y el comando salió con código 1.

Por qué «retry in a minute»: cuánto tarda el bloqueo en irse solo

El minuto del mensaje es la regla de los 60 s: cuenta desde la última vez que alguien actualizó la carpeta, no desde que viste el error. En la prueba del 12 de noviembre de 2026 con Claude Code 2.1.316, una carpeta de bloqueo recién creada y que nadie tocaba produjo el mensaje dos veces seguidas; repitiendo el comando 65 s después de crearla, Claude Code la retiró solo y siguió con la renovación normal. Una carpeta con fecha de hace 5 minutos se retiró al instante. Una con fecha 30 días en el futuro dio el mensaje también a los 65 s, porque su antigüedad nunca llega a 60 s; tras rmdir, el siguiente intento siguió el camino normal en 3 s. La carpeta antigua <config>.lock sola, sin la principal, también bastó para que saliera el mensaje.

El mensaje significa, en la práctica, que el bloqueo no se movió mientras esperabas. Cuando la prueba simuló un titular vivo, actualizando la fecha de la carpeta cada 2 s, Claude Code no mostró este mensaje: esperó unos 35 s y envió la petición con el token antiguo. Si lo ves, el titular murió, se atascó o dejó la carpeta atrás.

Desde la versión 2.1.282, el changelog de Claude Code dice que las peticiones ya no fallan durante hasta un minuto cuando el otro proceso se cerró o se mató a mitad de la renovación. El código de 2.1.316 solo hace esa recuperación rápida si el archivo owner demuestra que el proceso ya no existe en este equipo y si una opción que Anthropic activa a distancia lo permite, así que un proceso muerto puede recuperarse antes del minuto, pero no tiene por qué. Lo que no se probó: dos inicios de sesión reales compitiendo, Windows y la recuperación con archivo owner; esos casos salen de reportes de usuarios en GitHub.

Cuál es tu caso según lo que hacías justo antes

Lo que hacías justo antes del error suele señalar la causa. Cada fila resume reportes de usuarios en los issues de Claude Code en GitHub (el número va en la tabla) y, cuando existe, la versión que lo corrigió según el changelog oficial:

Comprobar quién tiene el bloqueo sin cambiar nada

Antes de cerrar o borrar algo, estas cuatro comprobaciones solo leen. Se basan en los elementos que creó Claude Code 2.1.316 en la prueba del 12 de noviembre y en las mismas comprobaciones que hace su código: si el número de proceso del archivo owner sigue vivo y si la fecha de la carpeta se mueve. Las rutas son las de ~/.claude; si usas CLAUDE_CONFIG_DIR, cámbialas por esa carpeta.

1. Mira qué bloqueos existen con ls -ld ~/.claude/.oauth_refresh.lock ~/.claude.lock (en PowerShell, Get-Item -Force "$HOME\.claude\.oauth_refresh.lock"). Si no existe ninguno, el bloqueo ya se liberó y basta con reintentar.
2. Lee el titular con cat ~/.claude/.oauth_refresh.lock.owner y apunta pid y procStart. Si el archivo no existe, la carpeta puede ser un resto de un proceso que salió antes de escribirlo.
3. Comprueba si ese proceso sigue vivo con ps -p PID -o pid,lstart,command, cambiando PID por el número que apuntaste (en PowerShell, Get-Process -Id PID). Si la hora de inicio coincide con procStart, es el mismo proceso; si no aparece o la hora no coincide, el titular ya no existe. Para ver todos los procesos de Claude Code, ps -ax -o pid,lstart,command | grep -i "[c]laude": ahí aparecen también la extensión de VS Code y --chrome-native-host.
4. Mira la fecha de la carpeta dos veces con unos 10 s de diferencia y compárala con date: en macOS, ls -ldT ~/.claude/.oauth_refresh.lock; en Linux, ls -ld --full-time ~/.claude/.oauth_refresh.lock; en PowerShell, (Get-Item -Force "$HOME\.claude\.oauth_refresh.lock").LastWriteTime. Si la fecha avanza, el titular está trabajando; si está quieta y tiene más de 60 s, está abandonada; si es posterior a la hora actual, no caducará nunca sola.

Cómo quitar el error, de menos a más arriesgado

El orden importa porque cada paso solo es necesario si el anterior no funcionó. Los tres primeros vienen de la documentación oficial y de la prueba del 12 de noviembre; el borrado manual en Windows es el que usaron los usuarios que lo reportaron.

1. Espera un minuto y vuelve a lanzar el comando. Si el otro proceso termina la renovación, tu sesión usa la sesión renovada; si el bloqueo estaba abandonado, el nuevo intento lo retira solo.
2. Si el mensaje vuelve, cierra el proceso concreto que encontraste en la comprobación: la otra ventana, Claude in Chrome o el script, o kill PID con el número del archivo owner. Después, reintenta.
3. Si no queda ningún proceso de Claude Code y la carpeta sigue quieta, o tiene fecha futura, bórrala con rmdir ~/.claude/.oauth_refresh.lock, y también rmdir ~/.claude.lock si es esa la que queda. rmdir solo borra carpetas vacías, así que no puede llevarse nada más. En Windows, el autor del issue #95236 de Claude Code en GitHub usó Remove-Item "$HOME\.claude\.oauth_refresh.lock" y el siguiente claude -p funcionó en 3,3 s; en el issue #95739 sobre bloqueos con fecha futura, rmdir recuperó la renovación al momento con las mismas credenciales.
4. Si el mensaje sigue saliendo sin ningún otro proceso, ejecuta /login dentro de Claude Code, o claude auth login desde la terminal. La documentación indica que volver a iniciar sesión no espera al bloqueo de renovación.

Si después de esto el error vuelve cada día, comprueba tu versión con claude --version y actualiza con claude update: varias de las causas de la tabla anterior tienen corrección en versiones concretas, que se detallan más abajo.

No borres .credentials.json ni el Llavero por este mensaje

Borrar las credenciales o reinstalar no arregla este error y sí te deja sin sesión. La documentación es explícita: el mensaje no significa que tu inicio de sesión haya sido rechazado, y ninguno de sus pasos incluye tocar las credenciales. Según los reportes de GitHub, la sesión guardada vive en %USERPROFILE%\.claude\.credentials.json en Windows, en ~/.claude/.credentials.json en Linux, WSL y contenedores, y en la entrada Claude Code-credentials del Llavero en macOS; el bloqueo es una carpeta aparte en la misma configuración. Tampoco uses pkill -f claude para «cerrar todo»: actúa sobre cualquier proceso con «claude» en su línea de comandos, y eso puede alcanzar otras aplicaciones, como la de escritorio de Claude. Cierra solo el proceso que tiene el bloqueo.

Qué versiones de Claude Code cambiaron este error y qué sigue abierto

Anthropic ha ido corrigiendo el bloqueo en varias versiones desde finales de agosto de 2026. Estas son las líneas del changelog oficial que tocan este error, con la fecha de publicación de cada versión en GitHub:

Antes de la versión 2.1.211, según la guía oficial, despertar el equipo de la suspensión podía hacer que dos sesiones renovaran con el mismo token y revocaran la sesión guardada, de modo que todas las ventanas pedían iniciar sesión a la vez.

Hasta la versión 2.1.322, ninguna línea del changelog menciona el EPERM de Windows al crear la carpeta, los bloqueos con fecha futura, --chrome-native-host, el proceso de caché de configuración de VS Code con ~/.claude.lock, ni los archivos .oauth_refresh.lock.owner.tmp.* que se acumulan en Windows (811 en un reporte del issue #108764, sin fallos visibles todavía). En los cerca de 27 issues de GitHub sobre este bloqueo, a 12 de noviembre de 2026, solo hay una respuesta de Anthropic: el 16 de agosto, un colaborador escribió en el issue #79688 de Claude Code que parecía un fallo real y que lo dejarían abierto; un bot lo cerró por inactividad el 19 de septiembre. Los tiempos de la prueba corresponden a la 2.1.316; la 2.1.318 y posteriores incluyen además las correcciones de comandos cortos y renovaciones lentas.

Windows: reportes de un bloqueo que no caduca solo

En Windows, lo que cuentan los usuarios no coincide con la prueba en macOS. En el issue #95236 (Windows 11, versión 2.1.272, lotes de claude -p), una carpeta .oauth_refresh.lock vacía siguió bloqueando tras esperar 180 s, aunque la regla del código es de 60 s, y el issue #62600 de Claude Code describe carpetas abandonadas tras cerrar procesos a la fuerza. Nadie lo ha explicado, y otro usuario de Windows con la 2.1.295 vio el error desaparecer solo en unos 40 s. Si la comprobación muestra que ningún proceso tiene la carpeta, en Windows no esperes más: bórrala. El EPERM del issue #91708 sobre sesiones simultáneas es otro problema, de muchos procesos compitiendo a la vez.

Que no se repita: VS Code, scripts, servidores y contenedores

La solución de fondo depende de dónde se juntan los procesos. Estas son las medidas que propone la documentación oficial o que usaron quienes reportaron cada caso:

• Si VS Code restaura varias ventanas por la mañana, un usuario del issue #90688 lo evitó con "window.restoreWindows": "one" en la configuración de VS Code; otros lanzan un claude -p antes de abrir el editor para que la renovación ocurra en un solo proceso. Si dudas de qué cuenta usa la extensión, sigue Comprobar la cuenta de Claude Code en VS Code: /status, inicio de sesión y ruta API.
• Para scripts, CI o servidores que no pueden iniciar sesión de forma interactiva, la documentación oficial recomienda autenticar con ANTHROPIC_API_KEY o con un token de larga duración generado con claude setup-token. Estas credenciales no pasan por la renovación de la sesión guardada; el token, eso sí, caduca y entonces da sus propios mensajes. Si sigues con la sesión guardada, los usuarios del issue #88583 de Claude Code lanzan primero una ejecución y esperan a que responda antes de arrancar el resto.
• Si un monitor, un banner de SSH o un script llama a comandos cortos como claude auth status, claude doctor, claude agents --json o claude --bg (las sesiones en segundo plano de Claude Code Agent View: cómo usar sesiones en segundo plano), actualiza primero: la 2.1.301 corrigió los comandos cortos que salían a mitad de renovación, y la 2.1.317 y la 2.1.318 lo completaron para renovaciones lentas en auth status y plugin. Esas dos últimas correcciones llegaron porque, después de la 2.1.301, hubo usuarios que siguieron perdiendo la renovación con claude plugin validate (2.1.302 y 2.1.303, issue #102265) y con claude auth status (2.1.311, issue #105645); el changelog no nombra doctor, agents --json ni --bg, y a 12 de noviembre de 2026 no hay reportes de comandos cortos posteriores a la 2.1.318 en los issues de GitHub sobre este bloqueo. Para un proceso cerrado o matado a mitad de renovación, la 2.1.282 corrigió que las peticiones fallaran hasta un minuto después; aun así, en un comentario del 31 de octubre en el issue #105729, sin versión indicada, una comprobación claude auth status --json cortada por tiempo dejó el bloqueo en 8 de 8 ejecuciones, así que no cortes Claude Code a mitad de ejecución y dale tiempo a terminar. Antes de la 2.1.301, los usuarios del issue #95822 sustituían esas llamadas por claude -p /usage.
• En contenedores y VMs, revisa el reloj del sistema, como sugiere la guía oficial cuando Claude Code pide iniciar sesión a menudo. En el issue #95236 se propuso ejecutar antes de cada trabajo find ~/.claude -maxdepth 1 -name .oauth_refresh.lock -type d -empty -mmin +1 -exec rmdir {} \;, que solo borra la carpeta si está vacía y lleva más de un minuto sin cambios; no detecta las fechas futuras.
• En Windows con muchas sesiones, un usuario del issue #91708 sustituyó los procesos sueltos por un único servidor claude remote-control con --capacity N.

Mensajes parecidos que no son este bloqueo

Failed to authenticate: OAuth session expired and could not be refreshed y Login expired no tienen que ver con el bloqueo: la renovación llegó al servidor y fue rechazada, y se tratan en Temporarily unable to authenticate en Claude: qué es y qué hacer. Si el texto empieza por Error during compaction: seguido de este mismo error, el fallo ocurrió al compactar la conversación; los pasos de ese caso están en Error al compactar en Claude Code: causa y solución por mensaje.

Cuando el mensaje dice Failed to refresh OAuth token: the disk that holds the Claude Code config directory (~/.claude by default), or your disk quota on it, is full, el bloqueo no tiene nada que ver: libera espacio en el disco donde está ~/.claude y vuelve a enviar el mensaje, porque iniciar sesión tampoco serviría mientras no se pueda guardar. Si el proceso que se queda con el bloqueo es el de Claude in Chrome y quieres revisar cómo está conectado, la configuración está en Claude in Chrome: instalar la extensión y conectar Claude Code.