What this usually means
spawn() failures fall into three buckets: the binary doesn't exist at the path you gave (ENOENT), the command arguments are incorrectly formatted as a single string without `shell: true`, or the child process crashes immediately because of environment variable differences (PATH, NODE_PATH). ENOENT specifically means the OS kernel returned 'No such file or directory' — not that the file is missing, but that the executable file itself cannot be found. EPIPE means the child process tried to write to stdout/stderr after you closed the stream, typically from calling .kill() or destroying the stream prematurely.
The first ten minutes — establish facts before touching code.
- 1Run `which <command>` to verify the binary exists on the same machine and PATH
- 2Check if you passed a single string as command instead of an array — this is the #1 cause of ENOENT
- 3Add `{ stdio: 'inherit' }` to see the actual error output from the child process
- 4Log `process.env.PATH` and compare to the PATH inside the child process by running `env` via spawn
- 5Test the exact command in a terminal with the same working directory and environment variables
The specific files, logs, configs, and dashboards that usually own this bug.
- searchThe spawn() call arguments — are they `spawn('cmd', ['arg1'])` or `spawn('cmd arg1')`?
- searchprocess.env.PATH at the time of spawn call
- searchcwd option — does the working directory exist and have the binary?
- searchstdout/stderr 'error' events — they emit EPIPE when the parent closes the stream
- searchThe child process exit code and signal — .on('exit', (code, signal) => ...)
- searchSystem logs: journalctl or /var/log/messages if the binary segfaults
- searchulimit -a output — RLIMIT_NPROC can cause EAGAIN which looks like ENOENT
Practical causes, not theory. These are the things you will actually find.
- warningCalling spawn() with a string command instead of an array (e.g., `spawn('ls -la')` instead of `spawn('ls', ['-la'])`)
- warningMissing or incomplete PATH environment variable — common in systemd services or IDEs
- warningBinary path is relative but cwd is not what you expect
- warningUsing shell syntax (pipes, redirects) without `{ shell: true }`
- warningClosing the child process stdin before it finishes writing — causes EPIPE
- warningThe binary exists but doesn't have execute permission
- warningOn Windows: spawned a .exe but didn't include the extension, or used cmd.exe incorrectly
Concrete fix directions. Pick the one that matches your root cause.
- buildAlways pass command and args as separate array elements
- buildSet `{ shell: true }` only if you need shell features (pipes, globs, env expansion)
- buildExplicitly set PATH with `{ env: { ...process.env, PATH: '/usr/bin:/bin' } }`
- buildUse `require('which')` or `which` command to resolve binary path before spawn
- buildAttach error listeners on both stdout and stderr streams to catch EPIPE
- buildUse `spawnSync` for quick diagnostics to see exact stderr output
- buildFor Windows: use `{ shell: 'cmd.exe' }` or `{ shell: 'powershell.exe' }` as needed
A fix you cannot prove is a guess. Close the loop.
- verifiedRun the same spawn command in a Node.js REPL and confirm it works
- verifiedCheck exit code 0 and no error events emitted
- verifiedCapture stdout and stderr fully — they should contain expected output
- verifiedTest with a deliberately wrong path to ensure your error handling triggers
- verifiedMonitor process count via `ps aux | grep <cmd>` to ensure no orphaned children
- verifiedUse strace (Linux) or Process Monitor (Windows) to see the actual execve syscall
Things that make this bug worse or harder to find.
- warningDon't catch the ENOENT error and ignore it — it hides real problems
- warningDon't set shell: true without understanding security implications (command injection)
- warningDon't assume the child process inherits the parent's environment — it does by default, but only if you don't pass `env`
- warningDon't forget to consume stdout/stderr streams — they will buffer and hang the process
- warningDon't use spawn for a one-liner shell command that fits in exec() — use exec() instead
- warningDon't kill the child process synchronously in a crash handler — it can cause deadlocks
The Phantom ENOENT in Production CI
Timeline
- 09:15Deploy to production triggers CI pipeline
- 09:17Pipeline fails: 'spawn eslint ENOENT' in lint step
- 09:20Check Jenkins node — eslint is installed globally: `which eslint` returns /usr/local/bin/eslint
- 09:25Run the same command manually: works fine
- 09:30Add `console.log(process.env.PATH)` before spawn — output shows PATH missing /usr/local/bin
- 09:35Compare to Jenkins slave's default PATH — the slave image was Alpine, which has minimal PATH
- 09:40Fix: set env.PATH explicitly in the spawn call
- 09:45Rerun pipeline — passes
I was on-call when the CI pipeline started failing for a linting step that had been green for weeks. The error was a classic `spawn eslint ENOENT`. My first instinct was to check if eslint was installed on the Jenkins slave. I SSHed in and ran `which eslint` — it returned `/usr/local/bin/eslint`. So the binary exists. Then I ran the exact same command our script used: `child_process.spawn('eslint', ['src/'])` — and it worked. That's when I knew it was an environment issue.
I added a quick `console.log(process.env.PATH)` right before the spawn call in our script. That's when I saw it: the PATH was missing `/usr/local/bin`. Our Jenkins pipeline was using a Docker container with an Alpine base image, and somewhere in the pipeline configuration, the PATH was being overridden to a minimal set. The manual SSH session had a different shell profile that added the global npm bin directory.
The fix was simple: in the spawn options, I set `env: { ...process.env, PATH: '/usr/local/bin:/usr/bin:/bin' }`. That ensured eslint was found regardless of the slave's default PATH. After that, the pipeline passed. The lesson: never assume the environment is the same as your shell. Log the actual environment variables at the point of spawn to catch these discrepancies.
Root cause
The Jenkins slave's PATH environment variable did not include /usr/local/bin, causing spawn to fail with ENOENT even though eslint existed.
The fix
Explicitly set the PATH in spawn options: `spawn('eslint', ['src/'], { env: { ...process.env, PATH: '/usr/local/bin:/usr/bin:/bin' } })`
The lesson
Always log the environment (especially PATH) when debugging spawn failures in CI or containerized environments. The default inheritance is not reliable when the parent process has a modified environment.
ENOENT from spawn() means the operating system's execve() syscall returned ENOENT. This happens not only when the file is missing, but also when the file exists but is not a valid executable (e.g., a directory, a script with no shebang, or a binary for a different architecture).
The most common cause is passing the command as a single string. `spawn('ls -la')` tells Node to look for an executable literally named 'ls -la' — which doesn't exist. Always use `spawn('ls', ['-la'])`. If you need shell parsing, use `{ shell: true }` but be aware of the security implications.
Another subtle cause is the PATH being incomplete. When you spawn a command by name (not full path), the system searches PATH. If your process's PATH differs from your shell's PATH (common in systemd services, IDEs, or CI), the binary won't be found. Log process.env.PATH before the spawn to confirm.
EPIPE errors occur when the parent process closes a stream that the child is still writing to. This often happens when you call `.kill()` on the child process but the child has already exited, or when you destroy the stdout stream prematurely.
A common pattern is: you spawn a long-running process, listen for 'data' on stdout, and then decide to abort. You call child.kill() and then try to read more data — but the child might have already flushed its output. The EPIPE error is emitted on the stream, not on the child process itself, so it's easy to miss if you don't have an 'error' listener on the stream.
To debug, attach error listeners on both stdout and stderr: `child.stdout.on('error', console.error)`. Also, check if you are explicitly closing stdin with `child.stdin.end()` before the child finishes reading — that can cause the child to exit prematurely and then write to a closed pipe.
By default, child_process.spawn() inherits the parent's environment. However, if you pass an `env` object, it completely replaces the environment — it does not merge. This is a frequent source of bugs: you only want to add one variable, but you inadvertently wipe out PATH, HOME, etc.
The fix is to always spread the current environment: `{ env: { ...process.env, MY_VAR: 'value' } }`. But beware that some platforms (like Docker) might have empty or minimal environments. In production, explicitly set PATH to a known good value.
Another issue is that process.env might not be fully populated in some contexts (e.g., Electron apps, AWS Lambda). In Lambda, the environment is controlled by the runtime, and binaries installed via npm might not be on PATH. Use the full path to the binary or set PATH explicitly.
On Windows, spawn() behaves differently. The default shell is cmd.exe, but it does not automatically resolve .exe, .bat, .cmd extensions. If you spawn 'myapp', it will look for 'myapp.exe' in PATH, but if the file is 'myapp.bat', it will fail. Use `{ shell: true }` to invoke the shell, which does resolve extensions.
Also, Windows has a different quoting mechanism. If you pass arguments with spaces, you need to quote them properly. Node.js does not handle quoting automatically unless you use shell: true. A common bug is spawning 'echo' with a string that contains spaces without shell: true — the child receives the entire string as one argument.
On Windows, the environment variable syntax is different (e.g., %PATH% vs $PATH). When setting env, use the appropriate format for the platform. Node.js does not convert between them.
When all else fails, use system tracing. On Linux, `strace -f -e execve node yourscript.js` will show every execve syscall, including the exact path being attempted and the error code. Look for lines like `execve("/usr/bin/node", ...) = 0` for success, or `execve("ls -la", ...) = -1 ENOENT` for failure.
On Windows, use Process Monitor (procmon) from Sysinternals. Filter by process name and look for CreateFile or CreateProcess operations. It will show the exact path being searched and whether it succeeded or failed.
These tools are invaluable for diagnosing spawn failures that only happen in production or under specific conditions. They reveal the exact arguments being passed to the OS, which can differ from what you think you're passing.
Frequently asked questions
Why does `spawn('node', ['script.js'])` work in my terminal but not in a systemd service?
Systemd services often run with a minimal environment. The PATH may not include /usr/local/bin or the node binary's directory. Also, the working directory (cwd) might be different. Explicitly set both env.PATH and cwd in the spawn options. Use `which node` to find the full path and pass that instead of just 'node'.
I'm getting ENOENT even though I'm using the full path to the binary. What's wrong?
Check that the file exists at that exact path and has execute permissions. Use `ls -la /full/path/to/binary`. If it's a script (e.g., .sh), it must have a valid shebang (#!/bin/bash) and the interpreter must be installed. Also, on some systems, files on NFS or FUSE mounts may not be executable. Try copying the binary to /tmp and running it from there.
How do I handle EPIPE errors gracefully?
Listen for 'error' events on both child.stdout and child.stderr streams. In the error handler, check if the error code is 'EPIPE' and log it accordingly. Also, ensure you are not closing stdin prematurely. If you need to abort, call child.kill() and then ignore subsequent EPIPE errors. You can also use the 'close' event on the child process to know when it's truly done.
Is there a difference between spawn and exec for debugging?
Yes. spawn() streams stdout/stderr, while exec() buffers them and passes them to a callback. For debugging, exec() is often easier because you get the full output in one place. However, exec() has a buffer size limit (default 200KB) and can cause memory issues. Use spawnSync() for synchronous debugging — it returns an object with stdout, stderr, and status.
Why does my child process hang when I spawn it?
The most common cause is that you are not consuming stdout or stderr. If the child writes enough to fill the pipe buffer (typically 64KB), it will block until the parent reads. Always set up data listeners on both streams. Another cause is that the child process is waiting for input on stdin — close it with child.stdin.end() if you don't need to send data.