Linux: musl binary preferred over glibc in v0.2.116 CLI auto-discovery

[gh-gill]

Summary

On Linux, SDK v0.2.116's CLI auto-discovery resolves to the musl variant before the glibc variant. If both platform packages are installed (via pnpm, which may install all optional deps for the current CPU), query() picks the musl binary path. Spawning a musl-linked ELF on a glibc system fails with ENOENT because the musl dynamic loader is missing — but the resulting error message says "Claude Code native binary not found", which is misleading on a system where the file very much exists.

Environment

• SDK: @anthropic-ai/claude-agent-sdk@0.2.116
• Node: v24.13.1
• OS: Ubuntu 24.04 (glibc 2.39)
• Package manager: pnpm 10.32.1
• Both installed: @anthropic-ai/claude-agent-sdk-linux-x64-musl@0.2.116 and @anthropic-ai/claude-agent-sdk-linux-x64@0.2.116

Reproduction

import { query } from '@anthropic-ai/claude-agent-sdk'

const stream = query({
  prompt: 'list models',
  options: {
    cwd: process.cwd(),
    maxTurns: 0,
    permissionMode: 'plan',
  },
})
await stream.supportedModels()

Actual

FAILED: Claude Code native binary not found at
  .../node_modules/.pnpm/@anthropic-ai+claude-agent-sdk-linux-x64-musl@0.2.116/
  node_modules/@anthropic-ai/claude-agent-sdk-linux-x64-musl/claude.
Please ensure Claude Code is installed via native installer or
specify a valid path with options.pathToClaudeCodeExecutable.

The file referenced in the error exists and is readable:

$ ls -la .../claude-agent-sdk-linux-x64-musl/claude
-rwxr-xr-x 1 user user 231918016 ... claude

$ .../claude-agent-sdk-linux-x64-musl/claude --version
bash: .../claude: cannot execute: required file not found   ← dynamic loader missing

$ .../claude-agent-sdk-linux-x64/claude --version
2.1.116 (Claude Code)                                       ← glibc variant works

Passing pathToClaudeCodeExecutable to the glibc binary explicitly also works, confirming the SDK itself runs fine once the correct binary is selected.

Expected

Either (a) the SDK detects the host's libc and picks the matching binary, or (b) the SDK tries glibc first and only falls back to musl when glibc is absent (glibc is by far the more common Linux environment). The ENOENT at spawn time should also be handled so the fallback iteration actually reaches the next candidate.

Root cause

In sdk.mjs, the resolver function iterates candidates in this order on Linux:

function W7($, X=process.platform, J=process.arch) {
  let Q = X === "win32" ? ".exe" : ""
  let z = (X === "linux"
    ? [`@anthropic-ai/claude-agent-sdk-linux-${J}-musl`,
       `@anthropic-ai/claude-agent-sdk-linux-${J}`]
    : [`@anthropic-ai/claude-agent-sdk-${X}-${J}`]
  ).map((G) => `${G}/claude${Q}`)
  for (let G of z) {
    try { return $(G) } catch {}
  }
  return null
}

Two issues here:

1. The musl candidate is first. On a system where both optional deps are installed (common with pnpm), require.resolve succeeds for musl and that path is returned without ever considering glibc.
2. The try/catch guards require.resolve, not the downstream spawn. A musl binary that resolves but can't execute on glibc does not trigger fallback — the caller just gets a spawn ENOENT with a misleading error message.

Suggested fix

One of, in order of robustness:

1. Detect libc at runtime (e.g. check for /lib/ld-musl-* vs /lib64/ld-linux-*, or use process.report.getReport().header.glibcVersionRuntime) and pick the matching variant.
2. Reverse the array so glibc is tried first. Much simpler; works for the common case.
3. Spawn-probe each candidate (e.g. --version with small timeout) and only accept the first that actually runs.

Option 1 is the correct long-term fix, option 2 unblocks most users immediately.

Workaround

Pass pathToClaudeCodeExecutable explicitly, either to the glibc variant package binary or to a separately-installed @anthropic-ai/claude-code binary (e.g. from which claude).

[asafmor]

I’m already seeing this issue in v0.2.114, but I’m not sure which version introduced it.
I expected an environment variable to override pathToClaudeCodeExecutable, but there isn't one. This issue caught me by surprise.

[jasoncrawford]

I also ran into this. In my case, I was working in a devcontainer, and after I rebuilt the container, when I ran my app using the SDK inside the container, it would mysteriously crash immediately on running a query, usually with an EPIPE error (although sometimes the query iterable would throw a different error mentioning SIGTRAP).

rm -rf on the claude-agent-sdk-linux-x64-musl directory solved my problem for now.

node:events:502
      throw er; // Unhandled 'error' event
      ^

Error: write EPIPE
    at afterWriteDispatched (node:internal/stream_base_commons:161:15)
    at writeGeneric (node:internal/stream_base_commons:152:3)
    at Socket._writeGeneric (node:net:958:11)
    at Socket._write (node:net:970:8)
    at writeOrBuffer (node:internal/streams/writable:572:12)
    at _write (node:internal/streams/writable:501:10)
    at Writable.write (node:internal/streams/writable:510:10)
    at q9.write (file:///workspace/node_modules/@anthropic-ai/claude-agent-sdk/sdk.mjs:59:8964)
    at file:///workspace/node_modules/@anthropic-ai/claude-agent-sdk/sdk.mjs:61:5232
    at new Promise (<anonymous>)
Emitted 'error' event on Socket instance at:
    at emitErrorNT (node:internal/streams/destroy:169:8)
    at emitErrorCloseNT (node:internal/streams/destroy:128:3)
    at process.processTicksAndRejections (node:internal/process/task_queues:82:21) {
  errno: -32,
  code: 'EPIPE',
  syscall: 'write'
}

[jddubois]

I ran into this as well using npm.

I was able to solve it in my builds by overriding the specific optional dependencies for the musl binaries.

i.e. adding this to my package.json

"overrides": {
    "@anthropic-ai/claude-agent-sdk": {
        "@anthropic-ai/claude-agent-sdk-linux-x64-musl": "npm:@favware/skip-dependency@^1",
        "@anthropic-ai/claude-agent-sdk-linux-arm64-musl": "npm:@favware/skip-dependency@^1"
    }
}

[undesicimo]

Hit this on 0.2.118 running on ECS Fargate (node:24.14.0-bookworm, pnpm). Both linux-x64-musl and linux-x64 packages installed since neither declares a libc field ,pnpm can't distinguish them.

We're downgrading to 0.2.112 (last version before native binary packages were introduced) as a workaround until this is resolved.

[Number531]

Contributing a second reproduction with a narrower trigger: npm (which correctly filters optional deps by libc) also hits this, not just pnpm. The SDK resolves to the musl path even when the musl package is intentionally never installed.

Environment

• SDK: @anthropic-ai/claude-agent-sdk@0.2.119
• Base image: node:22-slim (Debian slim, glibc)
• Node: v22.x (as shipped with node:22-slim)
• Package manager: npm 10.9.x
• Install command: npm ci --omit=dev --ignore-scripts --legacy-peer-deps
• node_modules/@anthropic-ai/ contents post-install:
  • ✅ claude-agent-sdk/ (main)
  • ✅ claude-agent-sdk-linux-x64/ (glibc variant, binary present at mode 0755)
  • ❌ claude-agent-sdk-linux-x64-musl/ — never installed (npm correctly respects the libc: ['musl'] filter in the musl package's package.json)

Actual error at runtime

Claude Code native binary not found at
  /app/node_modules/@anthropic-ai/claude-agent-sdk-linux-x64-musl/claude.
Please...

Why this is a broader bug than the pnpm case

In the pnpm scenario, the SDK picks the wrong variant that is installed (the musl binary fails to run because the musl loader is missing on glibc). In the npm scenario, the SDK picks a variant that is not installed at all — the file literally doesn't exist. So the SDK's lookup order "musl first, then glibc" isn't just preferring a non-working musl binary when both exist; it's also not falling through to glibc when only glibc is available.

The fix suggested elsewhere in this thread — probe the runtime's actual libc before selecting the variant path — handles both cases. A secondary fallback (try glibc path if musl path doesn't exist) would handle the npm-only case even without a proper libc probe.

Impact

We merged a 0.2.97 → 0.2.119 upgrade with static package inspection confirming:

• Platform package @anthropic-ai/claude-agent-sdk-linux-x64 ships correctly (binary pre-chmodded 0755)
• scripts: {} — no postinstall needed
• Triple-gated os/cpu/libc filter keeps musl out under npm

All of that is true, but doesn't save us because the SDK's runtime lookup ignores the actual install state. Deployed → query() fails on first invocation → rolled back to 0.2.97.

Workaround we're adopting in the meantime (Dockerfile symlink, for anyone else hitting this under npm):

RUN mkdir -p /app/node_modules/@anthropic-ai/claude-agent-sdk-linux-x64-musl && \
    ln -sf /app/node_modules/@anthropic-ai/claude-agent-sdk-linux-x64/claude \
           /app/node_modules/@anthropic-ai/claude-agent-sdk-linux-x64-musl/claude

Hacky but zero-code-change. Points the musl lookup at the glibc binary, which runs fine on glibc Linux (the binary is a native glibc ELF; the path name is just a lookup key).

Happy to contribute a PR with the libc-probe fix if maintainers would welcome it.

[mitchellbreust]

Adding a root-cause writeup since the discussion above has many repros but no single trace of why it happens. Hit this on 0.2.138, Ubuntu 24.04, glibc 2.39, npm 10.

Two-layer bug

Layer 1 — packaging. @anthropic-ai/claude-agent-sdk-linux-x64-musl/package.json declares only:

{ "os": ["linux"], "cpu": ["x64"] }

npm 10+ supports a libc field on optional deps that filters by libc at install time. Because it's absent, npm installs the musl variant on every Linux x64 host alongside the glibc one. Same for pnpm. This is why @undesicimo and @Number531 both see both packages on disk — neither package manager has enough metadata to filter.

Layer 2 — runtime picker. The picker in sdk.mjs (deminified):

function pickBinary(resolve, platform = process.platform, arch = process.arch) {
  const candidates = platform === 'linux'
    ? [
        `@anthropic-ai/claude-agent-sdk-linux-${arch}-musl`,
        `@anthropic-ai/claude-agent-sdk-linux-${arch}`,
      ]
    : [...];
  for (const c of candidates) {
    try { return resolve(c); } catch {}
  }
  return null;
}

Selection uses require.resolve, which only checks that the package directory exists on disk — not whether the binary's ELF interpreter can be loaded. Because layer 1 means both packages exist, musl resolves first and gets handed to spawn(). The exec then fails because the binary's interpreter is /lib/ld-musl-x86_64.so.1, which doesn't exist on glibc. The "binary not found" error message is misleading — the file is present, it just can't be loaded.

Why @jddubois's overrides workaround works

Forcing @anthropic-ai/claude-agent-sdk-linux-x64-musl to an empty/no-op package via overrides (or pnpm.overrides) means require.resolve on the musl path either fails outright or finds an empty package without the binary. Either way, the picker falls through to the glibc path. It's a clean fix at the build-config layer.

Suggested fix (in priority order)

1. Add libc fields to the native packages. This is the most surgical fix and eliminates the install-time conflict for every consumer without code changes:

   // claude-agent-sdk-linux-x64-musl/package.json
   { "os": ["linux"], "cpu": ["x64"], "libc": ["musl"] }
   // claude-agent-sdk-linux-x64/package.json
   { "os": ["linux"], "cpu": ["x64"], "libc": ["glibc"] }

   Both npm 10+ and pnpm respect this. Anyone on those versions stops seeing the conflict immediately on next install.

2. Detect libc at runtime in the picker. Belt-and-suspenders for users on older npm or anyone with both packages already on disk:

   const onMusl = process.platform === 'linux'
     && !process.report?.getReport()?.header?.glibcVersionRuntime;

   glibcVersionRuntime is populated by Node when linked against glibc and undefined on musl — no extra subprocess, no ldd shelling out. Reverse the candidates array based on that flag and the picker matches the host.

3. PATH_TO_CLAUDE_CODE_EXECUTABLE env var. @asafmor asked for this — would make the workaround scriptable without code changes (deploy scripts could set it). Worth adding regardless of which fix above lands, since it gives users an escape hatch for unusual platforms (Alpine in glibc-ish container, custom mounts, etc.).

Workaround we shipped

For anyone who can't wait, the cleanest code-side fix bypasses the picker entirely by resolving the correct package ourselves and passing pathToClaudeCodeExecutable:

let cached: string | undefined;
let resolved = false;

export function getClaudeCodeExecutable(): string | undefined {
  if (resolved) return cached;
  resolved = true;

  const { platform, arch } = process;
  const onMusl = platform === 'linux'
    && !(process.report?.getReport() as { header?: { glibcVersionRuntime?: string } } | undefined)
      ?.header?.glibcVersionRuntime;

  const candidates = platform === 'linux'
    ? onMusl
      ? [`@anthropic-ai/claude-agent-sdk-linux-${arch}-musl/claude`,
         `@anthropic-ai/claude-agent-sdk-linux-${arch}/claude`]
      : [`@anthropic-ai/claude-agent-sdk-linux-${arch}/claude`,
         `@anthropic-ai/claude-agent-sdk-linux-${arch}-musl/claude`]
    : [`@anthropic-ai/claude-agent-sdk-${platform}-${arch}/claude`];

  for (const c of candidates) {
    try { return (cached = require.resolve(c)); } catch { /* try next */ }
  }
  return undefined;
}

// Then at every query() call:
query({ options: { pathToClaudeCodeExecutable: getClaudeCodeExecutable(), ... } });

Works on glibc Linux, musl Linux, Darwin, and Windows. Survives reinstalls and fresh servers because it's code, not environment.

Filed #323 with the same analysis before realising this was the canonical issue — happy for that one to stay closed as a duplicate.

[bubblesorted]

Workaround working in production — explicit pathToClaudeCodeExecutable with libc detection

Hit this exact bug today on Railway (Debian/glibc container) after bumping from ^0.2.17 → ^0.2.138. Every SDK call failed with:

Error: Claude Code native binary not found at
/app/node_modules/.pnpm/@anthropic-ai+claude-agent-sdk-linux-x64-musl@0.2.140/node_modules/@anthropic-ai/claude-agent-sdk-linux-x64-musl/claude

The binary the SDK was looking for didn't exist — pnpm correctly installed linux-x64 (glibc), not linux-x64-musl, because Debian doesn't match the musl libc filter. But the SDK's auto-discovery tries the musl path first regardless of host libc.

Reproduction

1. Any glibc-based Linux container (Debian, Ubuntu, Amazon Linux 2023, distroless debian variants — everything Railway/Fly/Render/Vercel uses by default).
2. pnpm v10 with no supportedArchitectures override (so only the host-matching platform binary is installed).
3. @anthropic-ai/claude-agent-sdk ≥ 0.2.116.
4. Call query() with any options. Throws spawn ENOENT, error message claims binary "not found" — but really, the SDK is asking pnpm for the wrong package's binary.

Workaround (works for us)

Resolve the correct platform package's binary path explicitly and pass it as pathToClaudeCodeExecutable:

import { createRequire } from 'node:module'
import path from 'node:path'

const require = createRequire(import.meta.url)

export function getClaudeCodeExecutable(): string | undefined {
  if (process.platform !== 'linux') return undefined
  if (process.arch !== 'x64' && process.arch !== 'arm64') return undefined

  const report = process.report?.getReport() as { header?: { glibcVersionRuntime?: string } } | undefined
  const isMusl = !report?.header?.glibcVersionRuntime
  const variant = isMusl ? `linux-${process.arch}-musl` : `linux-${process.arch}`
  const pkg = `@anthropic-ai/claude-agent-sdk-${variant}`

  try {
    const pkgJsonPath = require.resolve(`${pkg}/package.json`)
    return path.join(path.dirname(pkgJsonPath), 'claude')
  } catch {
    return undefined
  }
}

// Usage
const session = query({
  prompt,
  options: {
    pathToClaudeCodeExecutable: getClaudeCodeExecutable(),
    // ...
  },
})

Returns undefined on macOS/Windows so the SDK's normal discovery still runs there — no change to local dev.

Suggested upstream fix

process.report.getReport().header.glibcVersionRuntime is a reliable libc detector in Node (exists on glibc, missing on musl). The SDK's binary-discovery in bridge.mjs should:

1. Detect libc at runtime using glibcVersionRuntime.
2. Pick linux-{arch} for glibc, linux-{arch}-musl for musl — not try musl first.
3. As a safety net, fall back to glibc if musl path errors with ENOENT.

Happy to send a PR if helpful — the change is small and covered by existing platform tests if you have any.

Severity

Anyone bumping from pre-0.2.116 to current on a Debian/Ubuntu deploy target hits this immediately. The error message is misleading (says "not found" when the package isn't even installed). For our gateway it caused 38h of silent staleness while we hunted down two unrelated issues first (pnpm-lock drift, then this).

[undesicimo]

Actually the fix was simple,
just fix the path to the executable in the query options

import {
  query,
  type Options,
   ...
} from "@anthropic-ai/claude-agent-sdk";

  const options: Options = {
      pathToClaudeCodeExecutable: "/usr/local/bin/claude", // add this
      model: "claude-sonnet-4-6",
      effort,
      systemPrompt,
      maxTurns,
...
}

await query({ prompt, options }