Claude Code auto-update failed

Find your case

Anthropic changes the wording of these messages between releases. Each section below shows the current line and, where people still paste it, the older one.

• Auto-update failed · Run claude doctor
• The older wording with the npm command
• What claude doctor checks, and what it does not
• Finishing the update on each install method
• Errors claude update prints
• What does not help

How this page was checked

Anthropic's install and update troubleshooting is a single page with its own table of errors and symptoms at the top, and the auto-update failure has a row in that table. Each message this page prints was found verbatim in Anthropic's documentation, downloaded in its Markdown form on October 23, 2026, or is quoted from the bug report in Anthropic's repository that carries the older wording. Where a message comes from a user report rather than from the documentation, the section says so.

The terminal capture in the claude doctor section is the real output of that command, run on a throwaway machine on Claude Code 2.1.309, October 23, 2026. Nothing on that machine belongs to a user account whose configuration matters, and no private path is shown in the capture.

One thing this page cannot give you is a reproduction of the failed update itself. A failed auto-update needs a download that breaks part way, and no command produces one on request. The line, its meaning and every step under it rest on Anthropic's documentation and on the three bug reports named in the Sources section.

Auto-update failed · Run claude doctor

Auto-update failed · Run claude doctor

What it means. Claude Code tried to update itself in the background and the update did not install. Anthropic's troubleshooting page is direct about the first thing to do: you can keep working without doing anything. What is on disk still runs, and a version you already have keeps working even when a later update fails.

How to fix it

1. Open a terminal and run claude update in your shell. That is the step Anthropic's page gives, replacing the one the footer line suggests: it says the line points you to claude doctor, whose last-update-attempt line gives a date but no cause, so you run claude update instead to finish the update or to see why it failed.
2. If the update installs, it prints a line beginning Successfully updated from with the old and new version numbers. If you were already on the newest version, it prints Claude Code is up to date instead. On a Homebrew, WinGet or apk installation it prints Claude is up to date!.
3. If claude update fails too, read the error it prints and match it in the next section. Anthropic's page keeps the same advice: look the message up rather than retrying blind.
4. Nothing in this message tells you to reinstall, and Anthropic's page does not ask for one. An update that fails is a download or a file operation that failed, not a reason to remove a working installation.

What claude doctor adds here

Last update attempt: failed (install_failed)

That is the one line in the claude doctor report that relates to this failure, and Anthropic's page says plainly what it is worth: it gives a date but no cause. The reason the update failed is in what claude update prints, which is why the documented next step is to run that command rather than to read the report harder.

The older wording with the npm command

✗ Auto-update failed · Try claude doctor or npm i -g @anthropic-ai/claude-code

What it means. The same failure, from an older release of Claude Code that also suggested an npm reinstall on the same line. Anthropic's current documentation does not carry this wording anywhere; the line is quoted from the bug report that raised it, in Anthropic's own repository, which is where the longer form survives. If you searched for this exact sentence, you were looking at a version old enough that the fix offered on the line may fail for reasons the current documentation explains.

How to fix it

1. Treat it as the message above: run claude update from your shell, then match whatever error it prints in the next section of this page.
2. If you do reach for the npm command, use the form Anthropic's setup page recommends for an upgrade, npm install -g @anthropic-ai/claude-code@latest, and avoid npm update -g, which respects the version range from the original install and may not move you to the newest release.
3. If the npm command fails with ENOTEMPTY, that is a documented error with a documented fix, and it is the third case in the next section.

Why the line's own advice can look wrong

The report behind the older wording is worth reading for one reason: it shows both suggested remedies failing on the same machine. The npm command returned npm error code ENOTEMPTY, and claude doctor answered that the installation was healthy and ready for auto-updates, which is accurate and unhelpful at the same time. Anthropic's documentation matches: claude doctor prints read-only diagnostics, so it reports what it finds rather than repairing an update. Two open reports in Anthropic's repository make the same complaint about the current line, that it can stay on screen after the situation it describes has changed, and that claude doctor answers No installation issues found while the banner is still there. Those are user reports, not documented behaviour, and Anthropic's page does not describe the line persisting. What it does document is the one step that settles the question either way: run claude update and read what it prints.

What claude doctor checks, and what it does not

Anthropic describes claude doctor as printing read-only installation and settings diagnostics from the terminal without starting a session, including install health, settings-file validation errors, and any warnings with suggested fixes. It also reports the result of the last update attempt Claude Code recorded. It is the right first look when something about the install is wrong, and the wrong place to look for the cause of a failed download.

Here is the whole report from a working installation, run on Claude Code 2.1.309. The ... stands for a Remote Control block that reports whether the machine is signed in to the Anthropic API, which says nothing about the installation:

$ claude doctor
Claude Code doctor

Running: npm-global (2.1.309)
Commit: 1ce7e4ff2da8
Platform: linux-x64
Search: OK (bundled)
Auto-updates: enabled
Auto-update channel: latest
Last update attempt: none recorded
...
No installation issues found.

The first line names how Claude Code was installed and which version is running. Auto-updates: enabled and the channel line come from the settings Anthropic documents under auto-updates. On a machine whose update has failed, the last-attempt line reads Last update attempt: failed (install_failed) instead of none recorded. When a warning does apply, the report lists it with a suggested fix; Anthropic's page gives the macOS Keychain warning as an example, where the report begins with macOS Keychain is not writable.

claude doctor is not /doctor

They are two different tools and the names are easy to swap. claude doctor is the shell command, it never starts a session, and it changes nothing. /doctor is the slash command inside a running session, and Anthropic describes it as a setup checkup that diagnoses installation, settings, extension and CLAUDE.md problems and proposes fixes that Claude applies after you confirm. If claude will not start at all, the shell command is the one you can still run.

Finishing the update on each install method

Which fix applies depends on how Claude Code got onto the machine in the first place, and claude doctor's first line names it. Anthropic's setup page groups the methods this way.

Native installation

This is the installer Anthropic recommends. A native installation updates itself in the background, and so does an npm installation: Claude Code checks for updates on startup and periodically while running, downloads and installs them in the background, and the new version takes effect the next time you start Claude Code. On macOS and Linux it manages the launcher at ~/.local/bin/claude as a symlink into ~/.local/share/claude/versions/. If you replaced that launcher with a script or a symlink of your own, auto-update leaves it in place and your launcher decides which version runs, and to hand the launcher back to Claude Code you remove ~/.local/bin/claude and run claude update.

Two settings matter when an update keeps failing. The release channel decides whether you follow every release ("latest", the default) or a version about a week old that skips releases with major regressions ("stable"), and you change it in /config under Auto-update channel or in your settings.json. A newly launched model can need a version newer than the stable channel serves, so if you moved to stable and a model will not run, moving back to latest is the documented way out. The minimumVersion setting is a floor: background updates and claude update refuse to install anything below it.

npm installation

Upgrade with npm install -g @anthropic-ai/claude-code@latest. Anthropic's setup page warns against sudo npm install -g, which leads to permission problems, and it points at a specific case for this failure: when an npm global install cannot auto-update because the npm global directory is not writable, Claude Code shows a one-time notice at startup and claude doctor lists the fixes. The remedy Anthropic gives for npm permission errors is to switch to the native installer with the install command for your platform.

Homebrew, WinGet, and Linux package managers

None of these update themselves by default, so an auto-update failure is not the thing to chase here. Upgrade the way the package manager expects: brew upgrade claude-code or brew upgrade claude-code@latest for the cask you installed, winget upgrade Anthropic.ClaudeCode on Windows, and sudo apt upgrade claude-code, sudo dnf upgrade claude-code or apk upgrade claude-code on Linux. Homebrew offers two casks: claude-code tracks stable and claude-code@latest tracks latest, and the apt, dnf and apk repositories offer both channels too. If you want Claude Code to run the upgrade for you, Anthropic documents one setting for it, CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE set to 1, which covers Homebrew and WinGet but not apt, dnf or apk, because those commands need administrator rights. On WinGet the upgrade can fail while Claude Code is running, because Windows locks the executable, and Anthropic notes that Claude Code may tell you about an update before the package manager has it.

Turning the updater off instead

If you would rather update on your own schedule, DISABLE_AUTOUPDATER set to "1" in the env section of your settings.json stops the background check, and Anthropic says how to confirm it took effect: run claude doctor and check that the Auto-updates line reads disabled (set by env: DISABLE_AUTOUPDATER). That switch leaves claude update and claude install working. To block every update path, including the manual ones, use DISABLE_UPDATES instead.

Errors claude update prints

These are the documented messages you can arrive at after running claude update. Each is on Anthropic's install troubleshooting page under its own heading, and the steps below are the ones that page gives.

The connection dropped while downloading the update

The connection dropped while downloading the update (attempt 3/3: aborted). Check your network — proxies sometimes cut off large downloads.

Download timed out: exceeded the total deadline

The download did not finish. Claude Code retries a download that drops, stalls or fails its checksum, up to three attempts, and claude update writes Error: Failed to install native update on stderr before the message. A download that stays connected for more than ten minutes fails with the second line instead, and that one is not retried. Run claude update again; on a healthy network the next run usually succeeds. Behind a proxy, set HTTPS_PROXY before you run it, and if a corporate proxy keeps cutting the transfer, ask the network team to allow the full download from downloads.claude.ai.

Release verification failed for Claude Code

Release verification failed for Claude Code <version> (<reason>). The update was not installed.

Claude Code could not confirm the release it was about to install is genuine, so it installed nothing, and the version you already have keeps working. Read the value in parentheses: if it starts with sidecar_fetch_, run the same command again from your shell; any other value, try again later. If the message repeats with any value, Anthropic's page asks you to report the problem and include the full message.

Failed to fetch version from downloads.claude.ai

Failed to fetch version from downloads.claude.ai

The installer could not reach the download server, which usually means downloads.claude.ai is blocked on the network. Anthropic's check is one command, curl -sI https://downloads.claude.ai/claude-code-releases/latest, and the first line tells you which it is: a 200 means you reached it, a 403 usually means a proxy or network filter is blocking the host, and a 5xx is usually temporary. No output, Could not resolve host, or a timeout means the network is blocking the connection.

npm error code ENOTEMPTY during update or reinstall

npm error code ENOTEMPTY
npm error syscall rename
npm error path ...
npm error dest ...
npm error errno -39
npm error ENOTEMPTY: directory not empty, rename '...'

The paths are elided. npm could not move the old package directory aside while installing over an existing installation. The npm error path line names the directory it could not move; Anthropic's fix is to delete that directory and any leftover .claude-code-* directories next to it, which earlier interrupted runs can leave behind, and then reinstall. The command uses your global package directory, which npm root -g prints. If Zsh answers no matches found while you remove the leftovers, there were none to remove. This is the failure the older wording ran into: it is what that line's own npm i -g suggestion hit.

claude.exe missing after an update on Windows

If your terminal reports that claude is not recognized right after Claude Code updated on Windows, check whether %USERPROFILE%\.local\bin still contains claude.exe. To update on Windows, Claude Code renames the existing claude.exe aside to a backup and moves the new version into place, and if that fails and the rename back fails too, the directory keeps the backup and has no claude.exe. The backup is a file in the same directory whose name begins claude.exe.old. followed by a numeric timestamp, and Anthropic gives a one-line PowerShell command to rename the newest one back. If there is no such file, or claude still fails afterwards, reinstall instead with irm https://claude.ai/install.ps1 | iex. Anthropic notes that before version 2.1.281 Claude Code could delete the backup while claude.exe was still missing.

claude update or claude doctor hangs

Both commands scan your shell configuration files for an outdated claude alias: ~/.zshrc, ~/.bashrc, ~/.config/fish/config.fish, and on macOS the first of ~/.bash_profile, ~/.bash_login or ~/.profile that exists. When one of those paths is a directory, current versions skip it and both commands complete normally. Before version 2.1.214 a directory at one of those paths made both hang, with claude doctor producing no output at all and claude update stopping right after printing Checking for updates. If you are on an affected version, move the directory aside, or update by rerunning the install script, since claude update is the command that hangs.

EACCES: permission denied during installation

EACCES: permission denied

An install that fails on permissions names the path it could not create or write. On macOS and Linux the install writes to ~/.claude/downloads/, ~/.local/bin/, ~/.local/share/claude/, ~/.local/state/claude/, ~/.cache/claude/ and your global config file ~/.claude.json. The check is test -w ~/.local/bin && echo "writable" || echo "not writable", and the repair is to create the directory and set your user as owner. If you previously installed with npm and are hitting npm-specific permission errors, Anthropic's advice is to switch to the native installer.

What does not help

Three things this failure tempts people into, none of which is a documented step for it.

• Reading claude doctor as a repair. Anthropic describes it as read-only diagnostics. It gives the last update attempt a date but no cause, and on a machine whose install is otherwise healthy it reports that health, which is why the line can sit there while the report says the installation is fine. Anthropic's own next step is claude update.
• Reinstalling over a working install. Nothing in Anthropic's page for this message asks you to remove Claude Code. A failed update is a download or a file operation that failed, and a reinstall is a documented remedy for two specific cases only: the npm ENOTEMPTY error, and Windows losing claude.exe and its backup.
• Changing settings to make the banner go away. Setting DISABLE_AUTOUPDATER stops future background checks. It does not finish the update that failed, and the version on disk is the one that stays.

Several sessions and one update

A background update is easy to miss when several Claude Code sessions are open at once, and Anthropic documents one consequence of exactly that on shared storage: an auto-update of an npm installation in place removes the binary that sessions on other machines are still running, which is why the setup page suggests DISABLE_UPDATES when a machine's sessions need to stay on one version. Omniscio, the desktop app we make for running many Claude Code sessions at once, lists those command-line tools in Settings, under Connected Tools, with a one-click Update on each and a Check for updates you can run yourself. For Claude Code it runs claude update in the background on your computer, against the binary your sessions actually run, or winget upgrade when WinGet installed it, and it says whether the update started and whether it took.

Where to go next

This page is the deep page for one error family. Claude Code error messages explained is the index for the rest of them, from context and request-size errors to usage limits, authentication and MCP failures. If the message you are chasing is that claude is not found at all, the PATH checks are in that guide's own section, and Claude Code on Windows covers the Windows install end to end. The download page has the current installers if you want to start again on the native method.

Sources

Every message, meaning and step on this page rests on one of these. The date beside each one is the day it was read.

• Anthropic, Claude Code install and login troubleshooting, for the auto-update failure and what claude doctor's last-attempt line is worth, the connection-dropped and download-timeout messages, release verification, the download-server failure, npm ENOTEMPTY, the Windows claude.exe backup, the hang on a directory at a shell config path, the permission checks and the PATH fixes. Read October 23, 2026.
• Anthropic, Advanced setup, for the install commands, the auto-update behaviour of each install method, the release channel, minimumVersion, DISABLE_AUTOUPDATER and DISABLE_UPDATES, the npm upgrade command, the package-manager upgrade commands and what claude update prints on success. Read October 23, 2026.
• Anthropic, Claude Code troubleshooting, for the symptom table that maps the session-footer line to its fix and for the difference between /doctor and the shell command. Read October 23, 2026.
• Anthropic, CLI reference, for what claude doctor is and what it prints. Read October 23, 2026.
• Anthropic, slash commands, for what /doctor does inside a session. Read October 23, 2026.
• Anthropic, error reference, for the row that sends the session-footer message to the install troubleshooting page. Read October 23, 2026.
• Wording Anthropic's documentation does not carry, quoted from the report that raised it: #996 for the older line that names the npm command, and the same report's evidence that its own two suggestions failed together. Read through the GitHub API on October 23, 2026; the report was opened May 7, 2025 and was still open on that date.
• Two open user reports of the current line staying on screen after the situation changed: #81898 and #82408. Both read through the GitHub API on October 23, 2026. These describe behaviour Anthropic's documentation does not, so they are named here as reports and not as documented facts.

Anthropic's installation and setup pages change with most Claude Code releases, and the troubleshooting page keeps notes such as "Before v2.1.214" and "Before v2.1.281". Read them again before you trust a copy of this page from a few months back.

Common questions

What does "Auto-update failed · Run claude doctor" mean?

Claude Code tried to update itself in the background and the new version did not install. You keep working on the version you already have, and Anthropic's troubleshooting page says you can carry on without doing anything. To finish the update, run claude update in your shell rather than claude doctor.

Is my Claude Code installation broken?

Not necessarily. The line reports a failed update, not a failed install. claude doctor is what tells you whether the installation itself is healthy, and it prints a read-only report: install health, settings-file validation errors, and any warnings with suggested fixes.

What is the difference between claude doctor and /doctor?

claude doctor is the command you run in your shell before Claude Code starts, and it prints read-only diagnostics. /doctor is the checkup you run inside a session, and Anthropic describes it as diagnosing installation, settings, extension and CLAUDE.md problems and proposing fixes that Claude applies after you confirm.

Why does npm i -g @anthropic-ai/claude-code fail with ENOTEMPTY?

npm cannot move the old package directory aside. Anthropic's install troubleshooting page says to delete the directory the npm error path line names, plus any leftover .claude-code-* directories beside it, and then reinstall. To upgrade an npm install, Anthropic's setup page recommends npm install -g @anthropic-ai/claude-code@latest rather than npm update -g.

How do I update Claude Code if I installed it with Homebrew or WinGet?

Those installations do not update themselves by default. Run brew upgrade claude-code or brew upgrade claude-code@latest for the cask you installed, or winget upgrade Anthropic.ClaudeCode on Windows. Setting CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE to 1 lets Claude Code run the upgrade for you in the background.

Can I stop Claude Code updating itself?

Yes. Set DISABLE_AUTOUPDATER to 1 in the env section of your settings.json, which stops the background check but leaves claude update and claude install working. DISABLE_UPDATES blocks every update path, including manual ones.