anthropics / anthropics/claude-code
[BUG] `claude upgrade` reports success but leaves `bin/claude.exe` as the fallback stub — native binary not linked
- Dominant language
- Python
- Stars
- 145k
- Forks
- 23.1k
- PR merge metrics
- PR metrics pending
Description
### Preflight Checklist
- [x] I have searched [existing issues](https://github.com/anthropics/claude-code/issues?q=is%3Aissue%20state%3Aopen%20label%3Abug) and this hasn't been reported yet
- [x] This is a single bug report (please file separate reports for different bugs)
- [x] I am using the latest version of Claude Code
### What's Wrong?
### Environment
- OS: macOS 26 → 27 (Darwin 27.0.0), arm64
- Node: v24.15.0 via nvm
- Install type: global npm install (`~/.nvm/versions/node/v24.15.0/lib/node_modules/@anthropic-ai/claude-code`)
- Affected versions: reproduced across three consecutive upgrades (2.1.272 → 2.1.273, and again up to 2.1.276)
### Description
After running `claude upgrade`, the command prints a success message and `package.json` is updated to the new version, but `bin/claude.exe` is left as the placeholder shell-script stub instead of being replaced with the real native binary. Every subsequent `claude` invocation (from any directory, including `~`) fails with:
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
Or reinstall without --ignore-scripts / --omit=optional.
This is misleading: the platform-native optional dependency (e.g. `@anthropic-ai/claude-code-darwin-arm64`) *is* correctly downloaded and present in `node_modules` at the new version. The problem is specifically that `install.cjs`'s `placeBinary()` step — which copies/hardlinks the real binary over `bin/claude.exe` — never runs (or fails silently) as part of `claude upgrade`'s own update flow.
### Actual behavior
`claude upgrade` exits successfully while leaving `bin/claude.exe` as the ~200-byte stub script instead of the ~200MB native binary.
### Workaround
Manually re-run the postinstall script, which correctly finds and links the already-downloaded native binary:
```bash
node "$(npm root -g)/@anthropic-ai/claude-code/install.cjs"
This fixes it every time without a full reinstall, confirming the native binary was already present — claude upgrade just isn't invoking (or is failing at) this linking step.
### What Should Happen?
### Expected behavior
`claude upgrade` should leave a working `claude` binary — either by running the postinstall step itself after updating, or by not reporting success until the binary is actually linked.
### Error Messages/Logs
```shell
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
Or reinstall without --ignore-scripts / --omit=optional.
```
### Steps to Reproduce
### Steps to reproduce
1. Install `@anthropic-ai/claude-code` globally via npm under nvm.
2. Run `claude upgrade` when a new version is available.
3. Observe the "Successfully updated" message.
4. Run `claude --version` (or any other command) → fails with "claude native binary not installed".
### Claude Model
None
### Is this a regression?
Yes, this worked in a previous version
### Last Working Version
_No response_
### Claude Code Version
2.1.276
### Platform
Anthropic API
### Operating System
macOS
### Terminal/Shell
Terminal.app (macOS)
### Additional Information
_No response_
Contributor guide
No contributing guide indexed for this repository
Research direction
Reproduce the global npm upgrade with `claude upgrade`, then inspect the upgrade flow and `install.cjs`, especially the `placeBinary()` step. Compare the resulting `bin/claude.exe` with the native optional dependency and verify that `claude --version` works after upgrading without manually rerunning the installer.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, node.js
- Domain
- cli, release
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100