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

Claude Code tried to replace its own installed files and could not. Everything in this failure happens on your machine, before any request goes anywhere — so it is not an authentication problem, not a plan quota, not a model issue, and your API key is not involved. The session you are in keeps working on the old version; what broke is the update, not the tool.

The remedy in the message is the failure you just had

Read the second half of that line again. Auto-update is a global package install. npm i -g @anthropic-ai/claude-code is a global package install. They write to the same directory, with the same user, under the same permissions. If the update could not write there, the command being suggested cannot write there either.

The printed fallback is not a fallback — it is a rerun of the thing that just failed. That is why so many people report running it and getting nothing but a different-looking error, or worse, a success that they bought with sudo and then have to buy again every release.

Run it anyway, but for the right reason: the value of running the npm command by hand is not that it will work, it is that it prints why it cannot. The auto-updater collapses the underlying error into one line. npm does not. The code it prints — EACCES, EBUSY, ENOTEMPTY, a network error — is the whole diagnosis, and you cannot get it from the message in the terminal.

The first half of the line is genuinely useful and unrelated. claude doctor runs read-only installation and settings diagnostics from the shell without starting a session, which is exactly what you want when the CLI is in a state where you do not trust it to start.

Is retrying useful?

No. Nothing changes between attempts.

File ownership, directory permissions, and your PATH are the same one second later. If the update failed because it cannot write to the install directory, it will fail that way on every launch, forever, and the notice will keep appearing until you change something on disk. Repeated launches are not retries; they are the same deterministic failure re-rendered.

There is one exception worth exactly one attempt: if the underlying npm error is a network error rather than a permission error, the cause is a fetch that did not complete, and that class can be transient. Run the npm command once by hand and read the code. If it says EACCES or names a directory, stop retrying and read the next section. If it times out, you are on the installer’s version-fetch timeout instead, which is a network-path problem with a completely different fix.

Four causes, and the observation that picks yours

Each of these has a test that confirms or kills it in one command.

A global prefix you do not own. Run npm prefix -g to get the directory, then list its owner and compare it to whoami. If it is owned by root and you are not root, this is your cause — and the usual history is an install done with sudo at some point, which left root-owned files that your normal user can no longer replace.

More than one claude on PATH. Run command -v -a claude (where claude on Windows). More than one hit means the binary your shell runs and the one the updater manages may be different files — a version manager install, a package manager install, and an npm global install can coexist happily and update independently. The symptom that gives this away: the update reports success, and claude --version still prints the old number.

A file in use. On Windows a running executable cannot be overwritten. If the error names EBUSY or a locked file, something is still running — a second terminal, an editor with an integrated session, a background process.

The fetch never finished. A timeout or connection reset from npm means you never got the package, and no amount of permission fixing will help. Follow the timeout link above.

Fixing each one

Root-owned global prefix — point npm’s global prefix at a directory your own user owns. npm config get prefix shows the current one; npm config set prefix changes it; then put that directory’s bin on your PATH and install again as yourself. This is more typing than sudo npm i -g, and it is the difference between fixing the problem and renting a fix until the next release.

Be clear about what sudo actually buys you here. It installs files owned by root, which your user still cannot replace, so the next unattended auto-update fails exactly the same way — you have re-armed the failure while appearing to solve it. It also runs a package’s install scripts with full privileges. If you are on a machine you administer and you choose it knowingly for one install, that is your call; it is not a fix, and it should not be the first thing you try.

Multiple installs — decide which one you want and remove the others, then re-check with command -v -a claude. One path, one owner, one updater.

Locked file on Windows — close every process that could be holding it, including editor-integrated sessions, then run the install again from a fresh shell.

A machine someone else administers — if a managed settings file exists at the enterprise path for your OS (/Library/Application Support/ClaudeCode/ on macOS, /etc/claude-code/ on Linux and WSL, C:\Program Files\ClaudeCode\ on Windows), the box is centrally managed and the install directory may be read-only on purpose. /status shows which settings sources are actually active. Ask for the update rather than working around it.

For which install methods are supported on your platform, use the official Claude Code install documentation on code.claude.com — install paths and installer behavior are the part of this that differs by platform and by how you originally installed, and a guess here costs you an afternoon.

Confirming it, not just silencing it

Three checks, in this order. command -v -a claude returns exactly one path. claude --version prints the version npm said it installed. And the directory that path lives in is owned by your user — that last one is what separates “updated once” from “will update unattended next time”, and it is the only check that predicts the future. Anything short of it means you will read this page again in a week.

Nearby errors that look like this one

A startup crash that names a version string is not an update failure: ERROR Invalid Version means something parsed a version and rejected it, and the tool is already installed. A timeout while fetching the release channel is a network-path problem, where nothing has been written to disk yet. If you are not sure which of the three you have, the AI coding error triage tool sorts them by the observations above.