Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix SDK: misleading 'executable not found' error when PATH is missing from child env [1 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
anthropics/claude-code#48143•Fetched 2026-04-15 06:31:57
View on GitHub
Comments
1
Participants
2
Timeline
5
Reactions
0
Author
cyrusagentcyrusagent
Participants
cyrusagentcyrusagentgithub-actions[bot]github-actions[bot]
Timeline (top)
labeled ×4commented ×1

Error Message

ReferenceError: Claude Code executable not found at /path/to/cli.js. Is options.pathToClaudeCodeExecutable set?

Root Cause

In sdk.mjs, the spawn error handler checks NK(error) (likely ENOENT) and blames cli.js:

if (NK(p$)) {
  let j4 = o0
    ? `Claude Code native binary not found at ${G}. Please ensure Claude Code is installed...`
    : `Claude Code executable not found at ${G}. Is options.pathToClaudeCodeExecutable set?`;
  this.exitError = ReferenceError(j4);
}

But ENOENT can come from the command (node/bun) not being found, not just the script argument. The error handler doesn't distinguish between the two.

Code Example

ReferenceError: Claude Code executable not found at /path/to/cli.js. Is options.pathToClaudeCodeExecutable set?

---

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

for await (const msg of query({
  prompt: "hello",
  options: {
    env: {
      // No PATH — node binary can't be found
      SOME_VAR: "value",
    },
  },
})) {
  console.log(msg);
}

---

if (NK(p$)) {
  let j4 = o0
    ? `Claude Code native binary not found at ${G}. Please ensure Claude Code is installed...`
    : `Claude Code executable not found at ${G}. Is options.pathToClaudeCodeExecutable set?`;
  this.exitError = ReferenceError(j4);
}
RAW_BUFFERClick to expand / collapse

Bug

When env is passed to query() without PATH, the SDK spawns node cli.js but the OS can't find node (ENOENT). The SDK misinterprets this as cli.js not being found and throws:

ReferenceError: Claude Code executable not found at /path/to/cli.js. Is options.pathToClaudeCodeExecutable set?

This is misleading — cli.js exists and pathToClaudeCodeExecutable is set correctly. The actual problem is node not being on PATH.

Reproduction

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

for await (const msg of query({
  prompt: "hello",
  options: {
    env: {
      // No PATH — node binary can't be found
      SOME_VAR: "value",
    },
  },
})) {
  console.log(msg);
}

Root cause

In sdk.mjs, the spawn error handler checks NK(error) (likely ENOENT) and blames cli.js:

if (NK(p$)) {
  let j4 = o0
    ? `Claude Code native binary not found at ${G}. Please ensure Claude Code is installed...`
    : `Claude Code executable not found at ${G}. Is options.pathToClaudeCodeExecutable set?`;
  this.exitError = ReferenceError(j4);
}

But ENOENT can come from the command (node/bun) not being found, not just the script argument. The error handler doesn't distinguish between the two.

Suggested fix

Either:

  1. Check if the ENOENT is for the command vs the script argument
  2. Include both paths in the error message: "Failed to spawn '${executable} ${pathToClaudeCodeExecutable}': ${error.message}"
  3. Or at minimum, mention that PATH might be the issue when env is explicitly provided

Environment

  • @anthropic-ai/[email protected]
  • macOS, Node.js v22.17.1
  • pnpm monorepo (symlinked node_modules)

🤖 Generated with Claude Code

extent analysis

TL;DR

The issue can be fixed by modifying the error handler in sdk.mjs to distinguish between the command and script argument when encountering an ENOENT error.

Guidance

  • Check the env object passed to query() to ensure it includes the correct PATH environment variable, allowing the OS to find the node executable.
  • Modify the error handler in sdk.mjs to include both paths in the error message, providing more informative error messages.
  • Consider adding a check to verify if the node executable is in the system's PATH when env is explicitly provided.
  • Review the options.pathToClaudeCodeExecutable setting to ensure it is correctly configured.

Example

// Example of how to modify the error handler in sdk.mjs
if (NK(p$)) {
  const errorMessage = `Failed to spawn '${executable} ${pathToClaudeCodeExecutable}': ${error.message}`;
  this.exitError = ReferenceError(errorMessage);
}

Notes

The provided fix assumes that the issue is solely related to the error handling in sdk.mjs. However, the root cause may be more complex, and additional debugging may be required.

Recommendation

Apply workaround: Modify the error handler in sdk.mjs to provide more informative error messages, and ensure the env object includes the correct PATH environment variable. This will help identify and resolve the issue more efficiently.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#embedding generation#cache error#pipeline error#runtime error#dependency conflict

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

claude-code - 💡(How to fix) Fix SDK: misleading 'executable not found' error when PATH is missing from child env [1 comments, 2 participants]