claude-code - 💡(How to fix) Fix [DOCS] Auto-update docs omit retry and failure diagnostics added in v2.1.147

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/setup

Section/Topic

Update Claude Code → Auto-updates and Update manually

Current Documentation

The setup page currently says:

Native installations automatically update in the background. You can configure the release channel to control whether you receive updates immediately or on a delayed stable schedule, or disable auto-updates entirely.

Claude Code checks for updates on startup and periodically while running. Updates download and install in the background, then take effect the next time you start Claude Code.

Known issue: Claude Code may notify you of updates before the new version is available in these package managers. If an upgrade fails, wait and try again later.

To apply an update immediately without waiting for the next background check, run: claude update

What's Wrong or Missing?

The update docs describe the happy path, but they do not document the updater failure behavior added in changelog v2.1.147:

Improved auto-updater: retries transient network failures, reports specific error categories and OS error codes on failure, and shows the current version when an update fails

That leaves a gap in the main update guide:

A. Automatic retry behavior is undocumented

Users are told to "wait and try again later," but the docs do not say Claude Code now retries transient network failures automatically before surfacing a failure.

B. Failure diagnostics are undocumented

The docs do not explain that updater failures now report a specific error category and OS error code, which is useful when troubleshooting proxy, filesystem, or platform-specific update failures.

C. The failure state does not mention version visibility

The docs do not say the failure message now includes the currently installed version, which helps users confirm whether they are still on the old version after a failed update.

Suggested Improvement

Add a short troubleshooting note or subsection under Update Claude Code that documents the v2.1.147 updater behavior:

• Claude Code automatically retries transient network failures before giving up.
• If an update still fails, the message includes a specific error category and OS error code.
• Failed update messages also show the currently installed version so users can confirm what version they are still running.
• Clarify whether this behavior applies to both background auto-updates and claude update, and note where package-manager installs differ.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 3 pages affected