fix(claude): honor CLAUDE_BIN_PATH in dev mode for libc-mismatch hosts#1481
Merged
fix(claude): honor CLAUDE_BIN_PATH in dev mode for libc-mismatch hosts#1481
Conversation
📝 WalkthroughWalkthroughChecks Changes
Sequence Diagram(s)sequenceDiagram
participant Caller
participant Resolver
participant Env as Environment
participant FS as FileSystem
participant Config as Config/Bundled
Caller->>Resolver: resolveClaudeBinaryPath(config?)
Resolver->>Env: read CLAUDE_BIN_PATH
Env-->>Resolver: envPath (set / unset / empty)
alt envPath set and non-empty
Resolver->>FS: fileExists(envPath)
FS-->>Resolver: true
Resolver-->>Caller: return envPath
else file missing
FS-->>Resolver: false
Resolver-->>Caller: throw "CLAUDE_BIN_PATH is set but the file does not exist"
else envPath unset or empty
Resolver->>Resolver: if !BUNDLED_IS_BINARY -> return undefined (dev)
alt BUNDLED_IS_BINARY true
Resolver->>Config: check configClaudeBinaryPath
Config-->>Resolver: configPath (or none)
alt configPath set
Resolver->>FS: fileExists(configPath)
FS-->>Resolver: true/false
Resolver-->>Caller: return configPath or throw
else
Resolver->>Config: autodetect bundled binary
Config-->>Resolver: detectedPath or none
Resolver-->>Caller: return detectedPath or throw install instructions
end
end
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Review rate limit: 6/8 reviews remaining, refill in 8 minutes and 2 seconds.Comment |
Collaborator
Author
Review SummaryVerdict: minor-fixes-needed Your fix correctly hoists Blocking issues
Suggested fixes
Minor / nice-to-have
Compliments
Reviewed via maintainer-review-pr workflow (Pi/Minimax). Aspects run: code-review, error-handling, test-coverage, comment-quality, docs-impact. |
Wirasm
added a commit
that referenced
this pull request
Apr 29, 2026
- CHANGELOG entry under [Unreleased] / Fixed describing the dev-mode CLAUDE_BIN_PATH escape hatch (previously ignored). Notes that config-file path remains binary-mode-only and that env-loading + target-repo .env isolation are unchanged downstream. - Empty-string test pinning that CLAUDE_BIN_PATH='' falls through to undefined rather than throwing — protects against a future predicate typo that would treat empty as "set". - One-line note in ai-assistants.md "Binary path configuration" section pointing dev-mode users at the env-var override for the glibc/musl mismatch case. Skipped from the review: - The other two docs-page rewrites (configuration.md / troubleshooting.md): the error message itself names CLAUDE_BIN_PATH, and #1474 documents the use case publicly. One mention in ai-assistants.md is enough for discovery. - Type-style consistency tweaks in the test file: pure bikeshed.
The Claude Agent SDK auto-resolves its bundled native binary in [linux-x64-musl, linux-x64] order. On glibc Linux hosts (Ubuntu/Debian/ Fedora), Bun installs both via optionalDependencies and the musl variant is picked first; its ELF interpreter (/lib/ld-musl-x86_64.so.1) does not exist on glibc, so spawn fails and the SDK reports a misleading "binary not found" — the file is on disk, the loader is not. The documented escape hatch CLAUDE_BIN_PATH was dead code in dev mode: the resolver early-returned undefined when BUNDLED_IS_BINARY=false before ever reading the env var. The only workaround was patching node_modules. Move the env-var block above the BUNDLED_IS_BINARY return. Config-file path stays binary-mode-only — it's per-repo, not per-machine; env is the right knob for libc mismatches. Behavior preserved: - env unset → unchanged (undefined in dev, autodetect/throw in binary) - env set + file exists → resolved (was binary-only; now also dev) - env set + file missing → clear error (was binary-only; now also dev) Closes #1474
- CHANGELOG entry under [Unreleased] / Fixed describing the dev-mode CLAUDE_BIN_PATH escape hatch (previously ignored). Notes that config-file path remains binary-mode-only and that env-loading + target-repo .env isolation are unchanged downstream. - Empty-string test pinning that CLAUDE_BIN_PATH='' falls through to undefined rather than throwing — protects against a future predicate typo that would treat empty as "set". - One-line note in ai-assistants.md "Binary path configuration" section pointing dev-mode users at the env-var override for the glibc/musl mismatch case. Skipped from the review: - The other two docs-page rewrites (configuration.md / troubleshooting.md): the error message itself names CLAUDE_BIN_PATH, and #1474 documents the use case publicly. One mention in ai-assistants.md is enough for discovery. - Type-style consistency tweaks in the test file: pure bikeshed.
Wirasm
force-pushed
the
fix/claude-bin-path-dev-mode
branch
from
6e67d8a to
8188492
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (2)
packages/providers/src/claude/binary-resolver-dev.test.ts (1)
23-39: Prefer per-test spy teardown (afterEachor test-localtry/finally) to avoid leak-on-failure.Current cleanup is good, but moving spy restore to per-test teardown makes isolation more deterministic if a test exits early.
Refactor sketch
-import { describe, test, expect, mock, beforeEach, afterAll, spyOn } from 'bun:test'; +import { describe, test, expect, mock, beforeEach, afterEach, afterAll, spyOn } from 'bun:test'; @@ beforeEach(() => { delete process.env.CLAUDE_BIN_PATH; - fileExistsSpy?.mockRestore(); - fileExistsSpy = undefined; }); + + afterEach(() => { + fileExistsSpy?.mockRestore(); + fileExistsSpy = undefined; + });Also applies to: 51-74
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/providers/src/claude/binary-resolver-dev.test.ts` around lines 23 - 39, The tests currently restore the fileExistsSpy only in beforeEach and afterAll which can leak if a test fails early; change cleanup to per-test teardown by moving fileExistsSpy?.mockRestore() into an afterEach (or wrap each test body with try/finally to restore) so each test restores fileExistsSpy immediately after it runs; update the same pattern in the other block referenced (lines 51-74) so both occurrences of the fileExistsSpy mock are restored in afterEach (or via test-local try/finally) and set fileExistsSpy = undefined in that afterEach as well.packages/providers/src/claude/binary-resolver.ts (1)
5-12: Consider consolidating the glibc/musl rationale to one concise comment.The same platform-mismatch explanation is duplicated in two comment blocks; keeping one short canonical note will reduce documentation drift.
Also applies to: 71-73
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/providers/src/claude/binary-resolver.ts` around lines 5 - 12, Consolidate the duplicated glibc/musl platform-mismatch rationale into a single concise comment near the resolution order for pathToClaudeCodeExecutable: remove the repeated paragraph (the one also present around lines 71-73) and replace with one short canonical note that mentions the platform mismatch concern and that CLAUDE_BIN_PATH can override the auto-resolved per-platform binary; update the comment around the resolution list (referencing CLAUDE_BIN_PATH and pathToClaudeCodeExecutable) so it is the single source of truth.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@packages/providers/src/claude/binary-resolver-dev.test.ts`:
- Around line 23-39: The tests currently restore the fileExistsSpy only in
beforeEach and afterAll which can leak if a test fails early; change cleanup to
per-test teardown by moving fileExistsSpy?.mockRestore() into an afterEach (or
wrap each test body with try/finally to restore) so each test restores
fileExistsSpy immediately after it runs; update the same pattern in the other
block referenced (lines 51-74) so both occurrences of the fileExistsSpy mock are
restored in afterEach (or via test-local try/finally) and set fileExistsSpy =
undefined in that afterEach as well.
In `@packages/providers/src/claude/binary-resolver.ts`:
- Around line 5-12: Consolidate the duplicated glibc/musl platform-mismatch
rationale into a single concise comment near the resolution order for
pathToClaudeCodeExecutable: remove the repeated paragraph (the one also present
around lines 71-73) and replace with one short canonical note that mentions the
platform mismatch concern and that CLAUDE_BIN_PATH can override the
auto-resolved per-platform binary; update the comment around the resolution list
(referencing CLAUDE_BIN_PATH and pathToClaudeCodeExecutable) so it is the single
source of truth.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: a4d22e1e-d5bc-4052-942a-8a1cbcb13953
📒 Files selected for processing (4)
CHANGELOG.mdpackages/docs-web/src/content/docs/getting-started/ai-assistants.mdpackages/providers/src/claude/binary-resolver-dev.test.tspackages/providers/src/claude/binary-resolver.ts
✅ Files skipped from review due to trivial changes (1)
- packages/docs-web/src/content/docs/getting-started/ai-assistants.md
🚧 Files skipped from review as they are similar to previous changes (1)
- CHANGELOG.md
Merged
Wirasm
added a commit
that referenced
this pull request
Apr 29, 2026
Regression from #1481 (honor CLAUDE_BIN_PATH in dev mode). The CI workflow set `CLAUDE_BIN_PATH: ~/.local/bin/claude` in YAML `env:` blocks; YAML does not expand `~`, so the literal string was passed to the resolver. Before #1481, dev mode silently ignored the env var and the SDK auto-resolved its bundled binary — so the broken value was harmless. After #1481, dev mode honors it, the file-existence check fails on the literal `~`, and the smoke job aborts with "CLAUDE_BIN_PATH is set ... but the file does not exist". Move the env-var assignment into the run-step shell where `$HOME` resolves. Both e2e-claude and e2e-mixed-providers jobs are affected.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
archon workflow runfails immediately in dev mode (bun run dev:server). The Claude Agent SDK auto-resolves its bundled native binary in[linux-x64-musl, linux-x64]order, picks the musl variant first, but the musl ELF interpreter (/lib/ld-musl-x86_64.so.1) does not exist on glibc — spawn fails and the SDK reports a misleading "binary not found" error.CLAUDE_BIN_PATHis dead code in dev mode (early-returned before the env var is read), so the only workaround is patchingnode_modules.CLAUDE_BIN_PATHenv-var block inbinary-resolver.tsabove theBUNDLED_IS_BINARYearly return. Updatedbinary-resolver-dev.test.tsto reflect the new contract.assistants.claude.claudeBinaryPath) is intentionally still binary-mode-only — it's a per-repo setting, not a per-machine escape hatch. Autodetect and the throw-with-install-instructions paths also stay binary-mode-only. Binary-mode behavior is byte-identical to before.UX Journey
Before
After
Architecture Diagram
Before
After
Connection inventory:
process.env.CLAUDE_BIN_PATHLabel Snapshot
risk: lowsize: XScore(closest available; lives in@archon/providers)providers:claude-binary-resolverChange Metadata
bugcoreLinked Issue
Validation Evidence (required)
bun run validategates exit 0; both resolver test files pass (5 dev-mode + 9 binary-mode).Security Impact (required)
Yes, describe risk and mitigation: N/ACompatibility / Migration
CLAUDE_BIN_PATHis documented; semantics broaden only)Human Verification (required)
undefined(existing test)Side Effects / Blast Radius (required)
CLAUDE_BIN_PATHexported globally (e.g. for binary builds) and then runs dev mode will now have that path used instead of the SDK's bundled binary. This is the desired behavior (and matches what the env var name implies), but it is a behavior change for anyone who had the env var set without realizing dev mode was ignoring it. If the path is valid this is harmless; if the path is stale they'll see a clear error pointing at the path.Rollback Plan (required)
git revert bf8dabbe— single-commit revert restores prior behavior.unset CLAUDE_BIN_PATHto opt out without code changes.Risks and Mitigations
CLAUDE_BIN_PATHset in their shell may now hit the resolver-level error in dev mode where they previously didn't.Summary by CodeRabbit
Bug Fixes
Tests
Documentation
Chores