Claude Code auto update failed: la línea de claude doctor que dice por qué (y por qué reinstalar no lo arregla)

TL;DR Corre claude doctor desde tu shell y lee Last update attempt. Si dice success y tu versión no se mueve, tienes un launcher propio en ~/.local/bin/claude: bórralo y corre claude update. Si instalaste con npm, el directorio global no tiene permiso de escritura. Si dice connection dropped, murió la descarga. Y si Config install method no pone native, nunca hubo auto-update que pudiera fallar.

Te sale auto update failed al arrancar, o simplemente Claude Code no se actualiza: llevas semanas sin ver una novedad y claude --version sigue clavada en el mismo número. El update no funciona y no sabes por qué.

Claude Code comprueba si hay versión nueva al arrancar y cada cierto tiempo mientras funciona. La descarga y la instala en segundo plano, y la nueva versión entra la próxima vez que abres una sesión. Cuando ese proceso falla te lo dice, pero no te dice por qué.

El resultado del último intento sí queda guardado, y hay un comando que lo imprime.

claude doctor

Claude Code doctor

Running: native (2.1.237)
Path: /Users/juan/.local/share/claude/versions/2.1.237
Config install method: native
Auto-updates: enabled
Auto-update channel: latest
Last update attempt: success → 2.1.236 (2026-08-19)

No installation issues found.

Tres líneas hacen todo el trabajo: Config install method, Auto-updates y Last update attempt. Con ellas se distinguen las cuatro causas.

1. Dice success, pero tu versión no cambia

Es el caso desconcertante: el update funciona, claude --version sigue igual y llevas semanas sin ver una novedad.

En macOS y Linux el installer nativo gestiona ~/.local/bin/claude como un symlink hacia ~/.local/share/claude/versions/. Si en algún momento lo sustituiste por un script tuyo o por un symlink a otro sitio, el auto-update y claude update lo respetan: las versiones nuevas se instalan igual bajo versions/, pero es tu launcher el que decide cuál se ejecuta. claude doctor marca un launcher que el installer nativo no creó.

which -a claude
ls -la ~/.local/bin/claude

Si eso no apunta a un directorio de versions/, devuélvele el control:

rm ~/.local/bin/claude
claude update

Con un launcher propio, Claude Code además conserva en disco todas las versiones instaladas, porque no puede saber cuál necesitas.

2. Instalaste con npm y el directorio global no se puede escribir

Si el directorio global de npm no tiene permiso de escritura, el auto-update no puede hacer su trabajo. Claude Code muestra un aviso único al arrancar y claude doctor lista los arreglos disponibles.

El camino limpio es pasarte al installer nativo, que instala en tu directorio de usuario:

curl -fsSL https://claude.ai/install.sh | bash

No uses sudo npm install -g para esquivarlo. Y si intentas arreglarlo reinstalando por npm, puedes chocarte con un ENOTEMPTY: directory not empty al mover el paquete viejo. La línea npm error path nombra el directorio culpable:

rm -rf "$(npm root -g)/@anthropic-ai/claude-code"
rm -rf "$(npm root -g)/@anthropic-ai/.claude-code-"*
npm install -g @anthropic-ai/claude-code

3. Murió la descarga

The connection dropped while downloading the update
Download timed out: exceeded the total deadline

Literal y el más benigno de los cuatro. Comprueba la conexión y reintenta. Si se repite siempre, la documentación te manda a revisar la configuración de red, que es donde suelen estar un proxy corporativo o un firewall.

4. Nunca hubo auto-update

Si Config install method no dice native, no falló nada: Homebrew, WinGet, apt, dnf y apk no se actualizan solos. Aquí es donde brew upgrade claude-code no funciona, y casi siempre porque son dos casks distintos: claude-code sigue el canal stable y claude-code@latest el canal latest. Actualiza el que instalaste, no el otro.

Para que Claude Code lance el upgrade por ti en Homebrew y WinGet, añade esto a tu settings.json:

{
  "env": {
    "CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE": "1"
  }
}

En WinGet puede fallar mientras Claude Code está abierto, porque Windows bloquea el ejecutable. apt, dnf y apk siguen necesitando actualización manual porque piden permisos elevados. El mapa completo por método de instalación está en el tip de cómo actualizar Claude Code.

Forzar la actualización ahora

claude update

Current version: 2.1.237
Checking for updates to latest version...
Claude Code is up to date (2.1.237)

Cuando sí instala algo responde Successfully updated from <versión vieja> to version <versión nueva>. Las instalaciones gestionadas por Homebrew, WinGet o apk responden Claude is up to date!.

Apagar el auto-update a propósito

Si prefieres decidir tú cuándo llega la versión nueva:

{
  "env": {
    "DISABLE_AUTOUPDATER": "1"
  }
}

DISABLE_AUTOUPDATER solo apaga la comprobación en segundo plano; claude update y claude install siguen funcionando. Para bloquear todos los caminos, incluido el manual, usa DISABLE_UPDATES. Ojo con un efecto colateral: congelar Claude Code congela también los plugins, así que si quieres que tus marketplaces sigan refrescándose, acompáñalo de FORCE_AUTOUPDATE_PLUGINS=1.

Referencia

Documentación oficial: Auto-updates

Combina con

• /doctor dentro de la sesión, que además arregla lo que encuentra.
• Cómo saber si Claude Code está caído, cuando el problema no es tu instalación.