claude-code - 💡(How to fix) Fix [BUG] "✗ Auto-update failed" banner fires on a native install already running the latest channel version (transient check-failure surfaced as install-failure)

What's Wrong?

On a native install that is already on the latest channel version, Claude Code occasionally shows the startup banner:

✗ Auto-update failed · Try /status

…even though there is nothing to update and the install is completely healthy.

Investigation of my environment at the moment the banner appeared:

• Install method: native (~/.local/bin/claude → ~/.local/share/claude/versions/2.1.150)
• autoUpdatesChannel: "latest"; the latest channel manifest returns 2.1.150 — i.e. installed version == channel head, so no update was pending.
• Versions dir and bin dir both writable; 273 GB free disk.
• No leftover lock file or partial download in the versions dir.
• Network to the dist bucket returns HTTP 200 in ~0.4s.

So whatever failed was a transient failure of the background check/apply attempt itself, not a failed installation of a needed version. The updater then surfaces the same alarming red banner it would show for a genuinely broken install.

This differs from the existing reports, which are all real failed installs:

• #56189 — read-only/container npm install, asks for a suppress switch
• #54336 — Windows npm EBUSY file-lock during actual copy
• #51833 — FreeBSD ports install overwritten

What Should Happen?

The updater should distinguish a failed check (or "already current") from a failed install, and not show an alarming failure banner when:

1. the installed version already equals the channel target (nothing to do), or
2. a routine background check failed transiently with no consequence.

A benign/transient check failure could be silent (retry next cycle) or a low-key info note, reserving the red "✗ Auto-update failed" banner for an actual failed version swap.

Possible contributing factor (hypothesis)

I run many concurrent Claude Code sessions / background jobs. Multiple processes each firing their own background update check may collide on the update lock or the atomic symlink swap, with the loser reporting failure. A single-session user would rarely hit this. (Unverified — no lock/partial remained afterward — but offered as a likely amplifier.)

Steps to Reproduce

1. Native install on the latest channel, already at the latest published version.
2. Run several concurrent sessions / background jobs.
3. Intermittently the "✗ Auto-update failed" banner appears at startup despite being current.

Claude Code Version

2.1.150 (Claude Code)

Platform

Claude Pro/Max (CLI)

Operating System

macOS (Darwin 25.5.0, Apple Silicon)

Additional Information

Related: #56189, #54336, #53899 (note: CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 hides the banner but per #53899 also disables security-update traffic, so it isn't a clean opt-out).