anthropics / anthropics/claude-code

[BUG] `claude upgrade` reports success but leaves `bin/claude.exe` as the fallback stub — native binary not linked

Open
#95,297 0 comments 0 reactions 0 assignees View on GitHub
area:cli area:packaging bug has repro platform:macos
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.