[Bug] Auto-update fails with npm ENOTEMPTY rename error

Found 3 possible duplicate issues:

1. https://github.com/anthropic-ai/claude-code/issues/996
2. https://github.com/anthropic-ai/claude-code/issues/6864
3. https://github.com/anthropic-ai/claude-code/issues/7188

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

The bot is generating broken links.

It is using anthropic-ai as the organization, but it should be anthropics

Root Cause Analysis & Permanent Fix

I've experienced this exact same issue and conducted a thorough investigation. Here's the root cause and permanent solution:

Root Cause

The ENOTEMPTY error occurs because auto-updates attempt to run while Claude Code is actively running, causing file locks that prevent npm from renaming the installation directory.

Technical sequence:

1. Auto-update triggers while Claude process is active
2. npm plans to rename /node_modules/@anthropic-ai/claude-code → /.claude-code-[randomstring]
3. Running Claude process has file locks on executable files
4. Filesystem rename operation fails with ENOTEMPTY
5. Leaves corrupted temporary directories that block future updates

Evidence

From npm debug logs, the failure happens at the rename step:

silly reify moves {
  '/Users/[user]/.nvm/versions/node/v20.17.0/lib/node_modules/@anthropic-ai/claude-code': 
  '/Users/[user]/.nvm/versions/node/v20.17.0/lib/node_modules/@anthropic-ai/.claude-code-ArTm9x67'
}

Permanent Solution

The issue requires process-aware updates. I've implemented this fix:

1. Disable problematic auto-updates:

claude config set autoUpdates false --global

2. Create safe update script:

#!/bin/bash
# Stop Claude processes before updating
pkill -f "claude" 2>/dev/null
sleep 2

# Clean corrupted temp directories  
rm -rf /Users/$USER/.nvm/versions/node/*/lib/node_modules/@anthropic-ai/.claude-code-*

# Update safely
npm i -g @anthropic-ai/claude-code@latest

3. Weekly maintenance instead of daily failures:
Use controlled updates that properly handle process termination.

Environment Details

• OS: macOS 15.6 (24G84)
• Claude Code: 1.0.111
• Node: v20.17.0 (via nvm)
• npm: 10.8.2

Recommended Fix for Maintainers

Auto-updates should:

1. Check for running Claude processes before attempting update
2. Gracefully terminate or schedule update for next startup
3. Clean up temp directories from failed updates
4. Implement retry logic with exponential backoff

This is a common issue with self-updating applications and needs special handling to avoid file lock conflicts.

After implementing the above solution, the daily auto-update failures completely stopped.

For me I had to rm -rf ~/.npm/_npx, as I was using it with Vibe Kanban, which invokes npx directly

The ENOTEMPTY error occurs because auto-updates attempt to run while Claude Code is actively running, causing file locks that prevent npm from renaming the installation directory.

That's now how file locking on Unix works. Deleting (or equivalently atomically replacing) files or directories with open file descriptors is not an issue, and is in fact how updates are often handled.

Checking for running processes of the application to be updated is still a good idea, but is only required if it doesn't open all resource files it needs at startup time. If it's not done, there might be issues with currently running instances, but never with the update process itself.

ENOTEMPTY happens when trying to delete a non-empty directory or when trying to replace a non-empty directory with another.

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.

Still relevant

Same for me:

me@mycomp someFolder % ps -ef | grep -i claude
  502 72179 65368   0  9:17AM ttys009    0:00.00 grep -i claude
me@mycomp someFolder %

me@mycomp someFolder % npm i -g @anthropic-ai/claude-code
(node:67029) ExperimentalWarning: CommonJS module /opt/homebrew/lib/node_modules/npm/node_modules/debug/src/node.js is loading ES Module /opt/homebrew/lib/node_modules/npm/node_modules/supports-color/index.js using require().
Support for loading ES Module in require() is an experimental feature and might change at any time
(Use `node --trace-warnings ...` to show where the warning was created)
npm error code ENOTEMPTY
npm error syscall rename
npm error path /opt/homebrew/lib/node_modules/@anthropic-ai/claude-code
npm error dest /opt/homebrew/lib/node_modules/@anthropic-ai/.claude-code-2DTsDk1V
npm error errno -66
npm error ENOTEMPTY: directory not empty, rename '/opt/homebrew/lib/node_modules/@anthropic-ai/claude-code' -> '/opt/homebrew/lib/node_modules/@anthropic-ai/.claude-code-2DTsDk1V'
npm error A complete log of this run can be found in: /Users/me/.npm/_logs/2025-12-18T07_10_21_503Z-debug-0.log

Still having this issue. Deleting temp files and terminating all running claude instances worked.

I dont know if its been fixed in latest version(since the bug is still up). As Teo added,Fix is to add process-aware updates that:

• Check for running Claude processes before updating
• Schedule updates for next startup if processes are running
• Clean up temp directories from failed updates

Additional Data Point: Complete Package Corruption with Multiple Concurrent Instances

cc @bcherny - this is a significant issue affecting users running multiple Claude Code instances.

Environment

• OS: macOS 14.6 (Darwin 24.6.0)
• Node: v23.8.0 (via nvm)
• Claude Code: 2.1.4
• Installation: npm install -g @anthropic-ai/claude-code

What Happened

The @anthropic-ai/claude-code npm package was completely corrupted - not just a failed update, but the entire package contents were wiped. Only node_modules/ and vendor/ subdirectories remained; cli.js, package.json, and all other files were deleted.

$ ls /Users/ia/.nvm/versions/node/v23.8.0/lib/node_modules/@anthropic-ai/claude-code/
node_modules/
vendor/
# That's it - cli.js, package.json, everything else GONE

Root Cause Analysis

Multiple concurrent Claude instances were running (6+ instances, some from days/weeks ago that were never closed). The npm debug logs show TWO simultaneous npm install --global @anthropic-ai/claude-code commands at the exact same timestamp:

# From ~/.npm/_logs/2026-01-11T20_04_26_333Z-debug-0.log
6 verbose title npm install @anthropic-ai/claude-code
7 verbose argv "install" "--global" "@anthropic-ai/claude-code"
6 verbose title npm install @anthropic-ai/claude-code    # <-- DUPLICATE at same timestamp
7 verbose argv "install" "--global" "@anthropic-ai/claude-code"

This happened twice within 30 minutes (at 20:04 and again at 20:34), with concurrent installs each time.

The Race Condition

1. Multiple Claude instances check for updates
2. Multiple instances trigger npm install -g @anthropic-ai/claude-code simultaneously
3. npm's rename operation fails or corrupts because:

• Files are locked by running Claude processes
• Concurrent renames to temp directories collide

1. Package is left in corrupted state (partial deletion)

Reproduction Steps

1. Run Claude Code in multiple terminal sessions (5+ sessions)
2. Leave them running for extended periods (days)
3. Auto-update eventually triggers in multiple instances simultaneously
4. Package corruption occurs

Workaround Applied

Disabled auto-updates to prevent race condition:

// ~/.claude/settings.json
{
  "autoUpdates": false
}

# ~/.zshrc
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

Suggested Fix

1. Mutex/lock file before triggering auto-update to prevent concurrent updates
2. Check if another Claude process has the package locked before attempting update
3. Graceful degradation - if update fails, don't leave package in corrupted state
4. Version check before update - skip if already on latest (related to #14100)

This is the same underlying issue as #14100 (concurrent instance race condition) but with a more severe outcome (complete package corruption vs version downgrade).

This issue has been automatically closed due to 60 days of inactivity. If you're still experiencing this issue, please open a new issue with updated information.

This issue was closed incorrectly despite recent human comments. This behavior of the bot is reported at https://github.com/anthropics/claude-code/issues/16497. Please upvote that issue, so maybe it gets noticed.

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.