Error messages

Auto-update failed · Run claude doctor

Auto-update failed · Run claude doctor

Claude Code updates itself in the background, and when that goes wrong it leaves a red line at the bottom of the screen. On a standard install it reads:

Auto-update failed · Run claude doctor

Nothing is broken yet. The version you're running still works, since an update only takes effect the next time you start Claude Code (and in the code I read, the updater tries again every 30 minutes while a session is open). 174 issues in the anthropics/claude-code repo quote "Auto-update failed" as of September 25, 2026, and the rest of the line hints at which kind of install you have.

Four versions of the same line

I found two separate updaters in the version 2.1.282 code. The native installer gets the short line above. An npm install gets Auto-update failed · Try claude doctor or npm i -g @anthropic-ai/claude-code, which hands you the manual command (an older local npm install is told to run npm update inside ~/.claude/local instead). If npm can't write to its global folder, the line says so: no write permission to npm prefix. And on Windows there's claude.exe in use (close other Claude Code sessions, including VS Code), because Windows won't let a program file be replaced while it's running.

Homebrew, WinGet and the Linux package managers don't auto-update by default, according to the setup docs, so on those installs you'd normally update with brew upgrade claude-code or winget upgrade Anthropic.ClaudeCode.

What claude doctor tells you

The setup docs say claude doctor shows "the result of the most recent update attempt", and it does, as a Last update attempt: line. What it doesn't show is why. When I read the native updater's code, I found it sorts failures into about a dozen reasons, from network errors and timeouts to a full disk or an antivirus quarantining the download. Those reasons go to Anthropic's telemetry. The record on your machine (a small file called .last-update-result.json in ~/.claude) just says install_failed.

I'd skip straight to running the update yourself, because that's where the actual error shows up:

claude update

That runs the same download in the foreground and prints what went wrong. Anthropic's error reference covers the two download failures you're most likely to meet there. A dropped connection gets retried up to three times. A download that's still unfinished after 10 minutes fails as Download timed out: exceeded the total deadline (and isn't retried, since a link that slow won't do better on a second go). If you're behind a corporate proxy, the docs ask for downloads.claude.ai to be allowed through.

The notice that stays after nothing failed

This is the part that surprised me. A lot of recent reports come from people who were already on the latest version. In a June 2026 report on Windows, the network dropped during a session, the background check failed, and the red line never went away. Boris Cherny from Anthropic's Claude Code team confirmed it in August on 2.1.233 and 2.1.236: a check that fails for a passing reason "is stored as install_failed", even with nothing to install, and claude doctor keeps reporting Last update attempt: failed (install_failed) right next to "No installation issues found".

On a second thread he confirmed that running claude update when you're current prints "Claude Code is up to date" without clearing that stored failure. The original reporter checked again on September 23 and said it was still there in 2.1.280. So if claude update tells you you're up to date, I'd believe it. The red line is left over from a check that failed earlier.

npm installs and permissions

On npm installs, most of the reports I read trace back to npm itself. A May 2025 report with this exact title ran the suggested npm i -g and got ENOTEMPTY, npm failing to rename a leftover folder from an interrupted update. For permission errors, Anthropic's troubleshooting page points you to the native installer instead of npm:

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

If you're on Windows and seeing the claude.exe in use line, I'd close every other Claude Code session (the VS Code extension counts), then run claude update from a fresh terminal. One August 2026 reporter on an npm install found that was the only way their updates ever landed.

If you'd rather it stopped trying, DISABLE_AUTOUPDATER=1 turns off the background check while leaving claude update working. DISABLE_UPDATES=1 blocks both, which the docs describe as meant for teams that ship Claude Code through their own channels.