`claude update` fails with generic error when stale temp directory exists from previous failed update

AI Assistant:

Preflight Checklist

• [x] I have searched existing issues and this is not a duplicate
• [x] I am filing a single bug per report
• [x] I am using the latest version of Claude Code

What's Wrong?

When claude update or auto-update fails (e.g., due to disk space exhaustion), it leaves stale temp directories in the npm package location. Subsequent update attempts fail with a generic error message:

Error: Failed to install update
Or consider using native installation with: claude install

The actual underlying error (ENOTEMPTY from npm) is not shown to the user, and there's no guidance on how to resolve the issue.

What Should Happen?

1. The actual error should be displayed (e.g., "ENOTEMPTY: stale temp directory from previous failed update")
2. Recovery guidance should be provided (e.g., "Remove stale directory and retry: rm -rf ~/.config/npm-global/lib/node_modules/@anthropic-ai/.claude-code-*")
3. Ideally, Claude should detect and clean up stale temp directories before attempting an update

Steps to Reproduce

1. Install Claude Code via npm: npm install -g @anthropic-ai/claude-code
2. Fill disk to 0% free space (or simulate disk exhaustion)
3. Let auto-update attempt to run (or run claude update)
4. The update will fail and leave a stale temp directory like .claude-code-hubQN3oG
5. Free disk space
6. Try claude update again
7. Observe: Generic "Failed to install update" error with no actionable information

Is this a regression?

This never functioned - the error handling has always been generic for npm update failures.

Claude Code Version

2.1.11 (Claude Code)

(Bug was observed on 2.1.9, fixed by manual intervention, now running 2.1.11)

Platform

Anthropic API (Claude Max subscription)

Operating System

Arch Linux (Kernel 6.17.3-arch2-1) on ThinkPad T490

Terminal/Shell

• Bash 5.x
• tmux 3.x

Error Messages/Logs

From claude update:

Current version: 2.1.9
Checking for updates to latest version...
New version available: 2.1.11 (current: 2.1.9)
Installing update...
Using global installation update method...
Error: Failed to install update
Or consider using native installation with: claude install

Actual npm error (from npm update -g @anthropic-ai/claude-code):

npm error code ENOTEMPTY
npm error syscall rename
npm error path /home/user/.config/npm-global/lib/node_modules/@anthropic-ai/claude-code
npm error dest /home/user/.config/npm-global/lib/node_modules/@anthropic-ai/.claude-code-hubQN3oG
npm error errno -39
npm error ENOTEMPTY: directory not empty, rename '.../@anthropic-ai/claude-code' -> '.../.claude-code-hubQN3oG'

Directory state showing stale temp directory:

~/.config/npm-global/lib/node_modules/@anthropic-ai/
├── claude-code/           # Current install
├── .claude-code-hubQN3oG/ # STALE temp dir from failed update
└── sandbox-runtime/

Additional Information

Root cause chain:

1. Home directory ran out of space (0% free)
2. Auto-update attempted and failed mid-operation
3. npm tried to rename old package directory before installing new version
4. Rename failed, leaving stale .claude-code-* directory
5. All subsequent updates fail because destination directory already exists

Workaround (manual fix):

rm -rf ~/.config/npm-global/lib/node_modules/@anthropic-ai/.claude-code-*
npm cache clean --force
npm install -g @anthropic-ai/claude-code@latest --force
hash -r  # Clear bash hash table

Suggested improvements:

1. Surface the actual npm error to users instead of generic message
2. Detect stale .claude-code-* directories and offer to clean them up
3. Add retry logic after initial failure when conditions (disk space) improve
4. Document this failure mode in troubleshooting docs

npm configuration in ~/.bashrc (Linux, user-writable prefix, no sudo required):

# In ~/.bashrc
export npm_config_prefix="$HOME/.config/npm-global"
export PATH="$HOME/.config/npm-global/bin:$PATH"