[BUG] Auto-update creates broken claude.exe symlink on macOS, leaving CLI unusable after restart

[yashgoenka]

Preflight Checklist

• I have searched existing issues and this hasn't been reported yet
• This is a single bug report (please file separate reports for different bugs)
• I am using the latest version of Claude Code

What's Wrong?

After Claude Code auto-updates in the background, the global claude symlink is recreated pointing at a Windows binary path (claude.exe) that does not exist on macOS. As a result, any attempt to run claude from the terminal fails with zsh: permission denied: claude.

Inspecting the symlink:

$ ls -la /Users/me/.nvm/versions/node/v22.22.0/bin/claude
lrwxr-xr-x  1 me  staff  60 May  7 03:16 .../bin/claude -> ../lib/node_modules/@anthropic-ai/claude-code/bin/claude.exe

What Should Happen?

On macOS, the global claude symlink should point at the macOS entrypoint (e.g. cli.js or the equivalent JS entrypoint resolved from package.json's bin field), not at claude.exe. The CLI should remain runnable across restarts without manual reinstallation.

Error Messages/Logs

$ claude
zsh: permission denied: claude

$ claude -c
zsh: permission denied: claude

$ ls -la /Users/me/.nvm/versions/node/v22.22.0/bin/claude
lrwxr-xr-x  1 me  staff  60 May  7 03:16 /Users/me/.nvm/versions/node/v22.22.0/bin/claude -> ../lib/node_modules/@anthropic-ai/claude-code/bin/claude.exe

$ type -a claude
claude not found

Steps to Reproduce

1. Install Claude Code globally: npm install -g @anthropic-ai/claude-code (Node v22.22.0 via nvm, macOS).
2. Use Claude Code normally for several days with auto-updates enabled (default).
3. Restart the machine.
4. Open a new terminal session and run claude.
5. Observe: zsh: permission denied: claude.
6. Inspect the symlink and observe it now points at claude.exe, which does not exist on macOS.

Workaround that restores functionality (until the next auto-update repeats the bug):

rm -rf ~/.nvm/versions/node/v22.22.0/lib/node_modules/@anthropic-ai/claude-code
rm -rf ~/.nvm/versions/node/v22.22.0/lib/node_modules/@anthropic-ai/.claude-code-*
npm install -g @anthropic-ai/claude-code

Claude Model

Opus

Is this a regression?

Yes, this worked in a previous version

Last Working Version

No response

Claude Code Version

2.1.133 (Claude Code)

Platform

Anthropic API

Operating System

macOS

Terminal/Shell

Terminal.app (macOS)

Additional Information

• Node installed via nvm; v22.22.0 active. Other versions installed (v18.17.0, v20.19.5) but not in use.
• Conda also initialized in shell (base env active), shouldn't be relevant but mentioning in case PATH ordering matters.
• The symlink mtime updates without me running any install command, which is what points at the auto-updater.
• Likely fix area: the platform-detection branch in the auto-update flow appears to be selecting the Windows bin entrypoint (claude.exe) on macOS. Worth checking how the updater resolves the bin field from package.json vs. how the initial npm install -g resolves it — the initial install gets it right, the updater does not.
• Happy to provide full ~/.npm/_logs/ output, the resolved package.json bin field, or run any diagnostic commands if useful.

[github-actions]

Found 3 possible duplicate issues:

1. [BUG] v2.1.117 postinstall on macOS arm64 produces claude.exe (wrong filename), breaks claude command #52107
2. [Bug] Auto-update fails to update symlink to latest downloaded version #18700
3. Bug: claude command not found after npm install -g on macOS with Homebrew due to incorrect symlink #3172

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

[yashgoenka]

Did some additional digging into the bundled JS to trace what the auto-updater is actually doing. Posting in case it helps narrow this down — though the suspected-cause framing in my original report turns out to be wrong.

What I traced

The npm-global auto-update path dispatches like this:

else if (W === "npm-global") y("AutoUpdater: Using global update method"), k = "global", R = await e$_();

e$_() is not doing direct binary placement — it shells out to:

npm install -g @anthropic-ai/claude-code[@<version>]

So the binary placement happens through npm's normal install lifecycle, which means install.cjs's postinstall is what places and chmods the binary. The relevant block of install.cjs:

function placeBinary(src, dest) {
  // ... linkSync / copyFileSync logic ...
  if (process.platform !== 'win32') {
    chmodSync(dest, 0o755)
  }
}

So the chmod 0o755 step IS present in the postinstall path. My original "auto-updater forgets chmod" hypothesis is wrong as stated.

Refined hypothesis: the postinstall script isn't completing, leaving the placeholder stub in place

install.cjs only reaches the chmod call if placeBinary() succeeds. It returns early (without touching bin/claude.exe) if:

1. require.resolve('@anthropic-ai/claude-code-<platform>/package.json') throws — the matching optional dependency isn't installed (install.cjs lines ~142-175 in this version). The npm tarball ships bin/claude.exe as a small stub (< 4096 bytes, based on the size check in the EEXIST branch). Without postinstall completing, the stub stays in place.
2. Postinstall is disabled — e.g. npm config get ignore-scripts is true.
3. The placeBinary catch chain hits throw copyErr — both linkSync and copyFileSync failed, so chmod is skipped.

This still matches all the symptoms in my original report:

• zsh: permission denied: claude is exactly what zsh emits when a file on PATH lacks the +x bit.
• type -a claude saying "not found" is consistent: zsh's PATH scan filters by the executable bit, so a non-+x file is invisible to it.
• A bin/claude.exe of "looks like it exists" but isn't executable would be the stub left over from npm's tarball extraction — much smaller than the ~200 MB native binary.

In my original ls -la output I only captured the symlink (the 60 is the byte length of the target string), not the size of the symlink target. So I can't retroactively confirm whether the file in the broken state was the stub or the full binary.

Diagnostic next time it breaks

If anyone else hits this, two commands would be decisive in distinguishing the two failure modes:

# stub-left-in-place vs full-binary-without-+x
stat $(npm prefix -g)/lib/node_modules/@anthropic-ai/claude-code/bin/claude.exe

# is postinstall being silently skipped?
npm config get ignore-scripts

If the size is a few KB rather than the expected ~200 MB, postinstall didn't run (or returned early before placing the binary). If it's the full binary with no +x bit, then the failure is somewhere else.

Suggested fix area

Right now, when the optional dep isn't resolvable on macOS/Linux, the user is left with a non-executable stub at the path the global claude symlink points to, with no clear error path — zsh: permission denied is a particularly bad UX for what is actually "the postinstall couldn't find the matching native package". A more user-friendly fallback would be for install.cjs to:

• Write the stub (or a tiny shell script) that, when run, prints a clear "this install is incomplete, here's how to recover" message rather than failing as permission denied.
• chmod +x it unconditionally, even when no native binary was placed, so the message actually reaches the user.

Happy to test any of this if helpful.

[AIRGATECO]

Confirming a fresh reproduction of the "stub-left-in-place" failure mode hypothesized above, with the diagnostic data the previous comment asked for.

Install method: Anthropic native installer (~/.claude/local/), not npm-global via nvm. This widens the scope — the failure isn't specific to the npm install path.

Trigger: background auto-update from 2.1.123 to 2.1.144 on 2026-05-18 at 19:17 PT. Existing running session continued working; failure surfaced on next fresh terminal.

Symptoms (zsh, macOS Darwin 24.6):

/Users/<me>/.claude/local/claude: line 2: /Users/<me>/.claude/local/node_modules/.bin/claude: Permission denied
/Users/<me>/.claude/local/claude: line 2: exec: /Users/<me>/.claude/local/node_modules/.bin/claude: cannot execute: Undefined error: 0

Stub hypothesis confirmed by file size:

$ ls -la ~/.claude/local/node_modules/@anthropic-ai/claude-code/bin/claude.exe
-rw-r--r--  1 <me>  staff  500 May 18 19:17 .../bin/claude.exe

500 bytes, no execute bit. Matches the "few KB stub" prediction — not the full ~200 MB native binary. Postinstall did not complete on this auto-update.

Recovery (two commands):

chmod +x ~/.claude/local/node_modules/@anthropic-ai/claude-code/bin/claude.exe
node ~/.claude/local/node_modules/@anthropic-ai/claude-code/install.cjs

After that, claude --version returned 2.1.144 and new terminals launched normally.

Notable corroborating detail: running ~/.claude/local/claude --version after the chmod (but before running the postinstall) produced exactly the kind of fallback message the previous comment's "fix area" section recommends:

Error: claude native binary not installed.

Either postinstall did not run (--ignore-scripts, some pnpm configs)
or the platform-native optional dependency was not downloaded
(--omit=optional).

Run the postinstall manually (adjust path for local vs global install):
  node node_modules/@anthropic-ai/claude-code/install.cjs

So the helpful-fallback machinery is already wired up in some path — it just isn't reachable from the user's perspective when the stub lacks +x (zsh refuses to invoke it and emits permission denied instead). The previous comment's suggestion to chmod +x the stub unconditionally so this message reaches the user would resolve the bad UX for this install path too.

[Carsten-Timm]

Still happening — hit this from a background auto-update on macOS (Apple Silicon, Node v22.19.0 via nvm). Same broken claude.exe symlink, same zsh: permission denied: claude.

I can't say which version the failed auto-update was trying to install, since it was never runnable. After manual recovery, a clean npm install -g gave me v2.1.160, which works fine — so the bug is in the update step itself, not in any particular installed version.

One extra detail worth flagging: in my case the claude.exe in the package bin/ was only 500 bytes — too small to be a valid binary, so it looks like a truncated/corrupt write, not just a wrong-platform file.

The failed update also left the package directory in a state that blocked recovery — both npm uninstall -g and npm install -g failed with ENOTEMPTY on the rename to .claude-code-<hash>. Manual rm -rf of the package dir + the leftover temp dir was required before npm install -g would succeed (same workaround as in the issue).

+1 for the suggested fix — the symlink should resolve to the macOS entrypoint, not .exe.

[Carsten-Timm]

Still reproducing as of 2026-06-08 — a month after this was filed.

Environment: macOS (Apple Silicon / arm64), Node v22.19.0 (nvm), global npm install.

What happened: An auto-update from 2.1.156 failed (/doctor showed
Last update attempt: failed (install_failed)). The global claude symlink was
again pointing at bin/claude.exe, so new shells couldn't launch the CLI. An
already-running session kept working (it holds the old binary in memory), which
matches the "unusable after restart" title.

A couple of data points that may help:

1. Different failure shape this time. The claude.exe was a full ~219 MB
   file (not the ~500-byte truncated file seen in an earlier occurrence on this
   same machine). package.json reported 2.1.165, but the bin was unusable on
   macOS. So this looks like wrong-platform selection, not just a truncated
   download.

2. Recovery is blocked by a leftover dir (ENOTEMPTY). The failed update left
   a .claude-code-<hash> directory next to the package, so plain
   npm uninstall -g / npm install -g fails with:
   ENOTEMPTY: directory not empty, rename ... -> .../.claude-code-<hash>.
   Most users won't know how to recover from this.

Workaround that fixed it:
P="$(npm config get prefix)/lib/node_modules/@Anthropic-AI"
rm -rf "$P/claude-code" "$P/.claude-code-"*
npm install -g @anthropic-ai/claude-code@latest
hash -r
After the manual reinstall, file -L "$(which claude)" correctly reported
Mach-O 64-bit executable arm64 and claude --version returned 2.1.168 — so the
manual npm install detects the platform correctly; only the auto-updater
gets it wrong.

[Carsten-Timm]

Still reproducible on 2.1.173 (macOS / Apple Silicon, Node v22.19.0 via nvm) — but a different failure variant

Hit this again today (2026-06-11). Auto-update 2.1.158 → 2.1.173 failed with install_failed,
and claude was broken in new terminals. This time the broken bin/claude.exe was not a
Windows PE binary and not a truncated download — it was a 500-byte ASCII fallback stub.

file -L on the broken binary, captured before reinstalling:

  ~/.nvm/versions/node/v22.19.0/lib/node_modules/@anthropic-ai/claude-code/bin/claude.exe: ASCII text

First bytes of that stub:

  echo "Error: claude native binary not installed." >&2
  echo "" >&2
  echo "Either postinstall did not run (--ignore-scripts, some pnpm configs)" >&2
  echo "or the platform-native optional dependency was n...

So in this occurrence the auto-updater left the package's fallback shell stub in place — i.e.
the platform-native optional dependency (@anthropic-ai/claude-code-darwin-arm64) / the postinstall
step never completed. For us this is now the third distinct failure mode in this area:
(a) a truncated ~500-byte download, (b) a full ~219 MB but Windows-PE binary, and now (c) this
fallback stub.

ENOTEMPTY leftover present again: yes — a .claude-code-<hash> directory was sitting next to
claude-code, blocking npm's own uninstall/reinstall.

Extra data point on the workaround: even after manually deleting both claude-code and
.claude-code-*, the manual npm install -g @anthropic-ai/claude-code@latest itself exited with
ENOTEMPTY in npm's reify retire step:

  npm error code ENOTEMPTY
  npm error syscall rename
  npm error path .../@anthropic-ai/claude-code
  npm error dest .../@anthropic-ai/.claude-code-<hash>
  npm error ENOTEMPTY: directory not empty, rename '.../claude-code' -> '.../.claude-code-<hash>'

Despite the non-zero exit, the files actually landed correctly: bin/claude.exe became a real
Mach-O 64-bit executable arm64 (~223 MB), claude --version reported 2.1.173, and
~/.claude/.last-update-result.json flipped to "outcome":"success". So the non-zero npm exit
code is misleading here — worth verifying by content (file -L) rather than trusting the exit code.

Environment: macOS (Darwin 24.6.0), Apple Silicon arm64, Node v22.19.0 via nvm, npm 11.6.0,
zsh. Install method: global npm.