It is a common pattern in deploy scripts: create a scratch working directory, then spawn an external command inside it. Say a script like that fails one day with this:

spawn C:\Program Files\nodejs\node.exe ENOENT

The message names a full path to an executable, so the obvious move is to open that path and check. The file is right there. Something that exists is being reported as missing — and if you have ever hit that exact contradiction, this article is for you.

The twist: what was actually missing was not the executable, but the working directory (cwd) passed into spawn. The message names the executable, but the thing that had vanished was somewhere else entirely. Node’s child_process.spawn reports ENOENT without ever naming the path that was actually missing.

Why does the mix-up happen at all? An errno — the integer error code a system call returns when it fails, where a syscall is simply a program asking the OS kernel to do something like “open this file” or “start this process” — is supposed to tell you what went wrong. In spawn‘s world, though, the code alone cannot tell you whether the failure was the cwd or the executable. This article traces that gap down into the Node.js and libuv source (libuv is the C library that handles the event loop and process spawning underneath Node.js), and reports what actually happens on Windows and Linux when you go looking.

ENOENT already means two different things

The overlap is not an accident — Node’s own documentation for child_process.spawn() says so directly, in the description of the cwd option:

If given, but the path does not exist, the child process emits an ENOENT error and exits immediately. ENOENT is also emitted when the command does not exist.

A missing cwd gets ENOENT. A missing command also gets ENOENT. One error code, two unrelated causes — stated plainly in the official docs. ENOENT stands for “no such file or directory,” a general-purpose errno that Unix-family systems have used forever for “this path does not exist.” Being general-purpose is not a flaw by itself, but it does mean the code carries no memory of which path it was.

What the documentation does not say is how a caller is supposed to tell the two situations apart. Which property on the error object points to the cwd, if any? The rest of this article answers that by running actual code.

The measurements below come from two environments held to the same Node.js and libuv versions: Windows 11 Pro (build 10.0.26200), and the Docker node:22.12.0 image (Debian bookworm, WSL2 kernel 6.18.33.2). Both run Node.js v22.12.0 with libuv 1.49.1 underneath. Versions are pinned on purpose, so the only variable left is the OS.

The mugshot in the case file is always the executable

Two cases, run side by side with the same script: (A) a real executable with a cwd that has been deleted out from under it, and (B) a real cwd with a made-up executable name.

import { spawn } from 'node:child_process';
import { mkdtempSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';

const realDir = mkdtempSync(join(tmpdir(), 'probe-'));
const missingDir = join(realDir, 'no-such-dir');

function run(label, file, args, options) {
  return new Promise((resolve) => {
    const child = spawn(file, args, options);
    child.on('error', (err) => {
      console.log(label, '|', err.message);
      console.log('  code:', err.code, '| errno:', err.errno, '| path:', err.path);
    });
    child.on('close', resolve);
  });
}

// A: real executable + missing cwd
await run('A', process.execPath, ['-e', 'process.exit(0)'], { cwd: missingDir });
// B: missing executable + real cwd
await run('B', 'definitely-not-a-real-binary-xyz', [], { cwd: realDir });

On Windows:

A:
  message   : spawn C:\Program Files\nodejs\node.exe ENOENT
  code      : ENOENT
  errno     : -4058
  path      : C:\Program Files\nodejs\node.exe

B:
  message   : spawn definitely-not-a-real-binary-xyz ENOENT
  code      : ENOENT
  errno     : -4058
  path      : definitely-not-a-real-binary-xyz

On Linux, the shape is identical:

A:
  message   : spawn /usr/local/bin/node ENOENT
  code      : ENOENT
  errno     : -2
  path      : /usr/local/bin/node

B:
  message   : spawn definitely-not-a-real-binary-xyz ENOENT
  code      : ENOENT
  errno     : -2
  path      : definitely-not-a-real-binary-xyz

Whether it is A’s missing cwd or B’s missing executable, err.path holds the executable’s path every time — regardless of whether the executable exists or not. err.code and err.errno give no hint either. Looking at err.path alone, there is no way to arrive at “maybe it’s the cwd that’s missing.”

This is not an accident of implementation; it is written directly into Node.js itself, in lib/internal/child_process.js:

if (exitCode < 0) {
  const syscall = this.spawnfile ? 'spawn ' + this.spawnfile : 'spawn';
  const err = new ErrnoException(exitCode, syscall);

  if (this.spawnfile)
    err.path = this.spawnfile;

  err.spawnargs = ArrayPrototypeSlice(this.spawnargs, 1);
  this.emit('error', err);
}

err.path is assigned from this.spawnfile — the executable name — and nothing else. There is no variable holding the cwd anywhere nearby. Node.js only has one shape of error object, whether the underlying failure came from the executable side or the cwd side. So why does a cwd failure end up wearing the executable’s error at all? The answer is in how each OS actually starts a process.

POSIX: chdir runs before exec ever gets called

On POSIX systems like Linux and macOS, starting a new process is a two-step affair. First fork() duplicates the current process; then the child calls one of the exec family of functions, which replaces the child’s entire memory image with the requested executable. Between those two steps sits chdir() — the syscall that changes the current working directory.

libuv‘s POSIX-side process code (src/unix/process.c, in uv__process_child_init) has that ordering written straight into it:

  if (options->cwd != NULL && chdir(options->cwd))
    uv__write_errno(error_fd);

  /* … privilege switching, environment substitution, and signal mask setup go here … */

#ifdef __MVS__
  execvpe(options->file, options->args, environ);
#else
  execvp(options->file, options->args);
#endif

  uv__write_errno(error_fd);

chdir() runs before execvp(). If changing directories fails, the code never even goes looking for the executable. Either way, the resulting errno is written back to the parent through the same pipe, via the same uv__write_errno() call. A failed chdir and a failed execvp travel down the identical channel, so the parent process has no way to tell which one actually happened. That is exactly why err.path always ends up holding spawnfile — the fact that the real culprit was a missing directory is already gone by the time the error reaches Node.js.

Windows makes one call and folds many causes into it

Windows has nothing equivalent to fork(). libuv‘s Windows-side implementation (src/win/process.c) starts a process with a single Win32 API call, CreateProcessW:

  if (!CreateProcessW(application_path,
                      arguments,
                      NULL,
                      NULL,
                      1,
                      process_flags,
                      env,
                      cwd,
                      &startup.StartupInfo,
                      &info)) {
    /* CreateProcessW failed. */
    err = GetLastError();
    goto done;
  }

The eighth argument is lpCurrentDirectory — the new process’s working directory. Microsoft’s own documentation describes it as follows:

The full path to the current directory for the process. The string can also specify a UNC path.

(A UNC path is Windows‘s way of pointing at a network share, in the form \\server\share.)

Where POSIX splits process startup into three stages — fork, then chdir, then exec — Windows collapses the working directory and the executable into a single call. With no stages to separate, there is no natural point at which to distinguish why that one call failed. When CreateProcessW fails, GetLastError() returns a Windows-specific error code (one of the ERROR_* constants), and libuv converts it into a POSIX-style errno equivalent (one of the UV_* constants) through uv_translate_sys_error():

  /* Cleanup, whether we succeeded or failed. */
 done:
  err = uv_translate_sys_error(err);

Look at that conversion table (src/win/error.c) and a long run of cases all funnel into UV_ENOENT:

case ERROR_BAD_PATHNAME:                return UV_ENOENT;
case ERROR_DIRECTORY:                   return UV_ENOENT;
case ERROR_ENVVAR_NOT_FOUND:            return UV_ENOENT;
case ERROR_FILE_NOT_FOUND:              return UV_ENOENT;
case ERROR_INVALID_NAME:                return UV_ENOENT;
case ERROR_INVALID_DRIVE:               return UV_ENOENT;
case ERROR_INVALID_REPARSE_DATA:        return UV_ENOENT;
case ERROR_MOD_NOT_FOUND:               return UV_ENOENT;
case ERROR_PATH_NOT_FOUND:              return UV_ENOENT;
case WSAHOST_NOT_FOUND:                 return UV_ENOENT;
case WSANO_DATA:                        return UV_ENOENT;

“Malformed path,” “expected a directory but got something else,” “invalid drive,” “plain not found” — eleven causes of genuinely different character, all rounded down to the same UV_ENOENT (the last two are socket-related errors that arrive from an unrelated code path, yet still land in the same bucket). And this file has no case at all that returns UV_ENOTDIR (the errno that specifically means “expected a directory, found something else”).

What that shows is narrow: this particular conversion table has no exit toward UV_ENOTDIR. Whether Windows the operating system draws that distinction somewhere else is not something this table can answer either way — all it tells us is that whatever distinction might exist upstream does not survive the trip through this conversion.

That gap shows up as actual numbers once you break cwd four different ways and hand each one to spawnSync:

How cwd is broken	Windows	Linux (uid 1000)
Nonexistent directory	ENOENT (errno -4058)	ENOENT (errno -2)
cwd is a file	ENOENT (errno -4058)	ENOTDIR (errno -20)
Nonexistent drive/root	ENOENT (errno -4058)	ENOENT (errno -2)
Directory without permission	No error (chmod had no effect; not reproduced)	EACCES (errno -13)

Linux distinguishes three separate error codes; Windows collapses all three rows above into ENOENT. The last row, “directory without permission,” could not be reproduced on Windows at all — chmodSync(0o000) had no real effect there, so permission denial itself never triggered. That does not license the conclusion “Windows never returns EACCES for a cwd permission problem.” Locking the directory down properly with an ACL (access control list) might produce a different result; all that can be said here is that the chmod-based approach failed to reproduce it.

One more thing worth being precise about: from the JavaScript side, only the value after conversion to errno is ever visible, so which specific ERROR_* actually fired in any of these cases is not something this article claims to know. The conversion table clearly lists several distinct Windows errors funneling into UV_ENOENT, but pinning down “it was specifically ERROR_DIRECTORY in this run” is beyond what was verified.

The real trap: an 'error' event on one platform, a thrown exception on the other

Everything so far has been about what the error code means. What trips people up more in practice is how the error even reaches your code — and here the gap between platforms runs deeper still.

Node’s documentation describes it this way:

The 'error' event is emitted whenever:

The process could not be spawned.

…

Read plainly, that says: a failed spawn always shows up as an 'error' event. Try the case where cwd points at a file (which should trigger ENOTDIR) and watch what happens on each platform.

try {
  const child = spawn(process.execPath, ['-e', 'process.exit(0)'], { cwd: aFile });
  child.on('error', (err) => console.log('error event:', err.code, err.path));
} catch (err) {
  console.log('sync throw:', err.message, '| code:', err.code, '| path:', err.path);
}

On Windows, it arrives as an 'error' event, same as always:

message   : spawn C:\Program Files\nodejs\node.exe ENOENT
code      : ENOENT
path      : C:\Program Files\nodejs\node.exe

On Linux, no 'error' event fires at all. The spawn() call itself throws synchronously:

spawn() THREW synchronously
message   : spawn ENOTDIR
code      : ENOTDIR
errno     : -20
path      : undefined
spawnargs : undefined

And that thrown exception has neither path nor spawnargs attached. The exact same root cause — a cwd that turned out to be a file — reaches an 'error' handler on Windows and blows up as a synchronous exception on Linux. An 'error' handler alone, or a try/catch alone, will each miss one of the two platforms.

Why the split? It comes down to an allow-list in Node.js‘s own source (lib/internal/child_process.js):

if (err === UV_EACCES ||
    err === UV_EAGAIN ||
    err === UV_EMFILE ||
    err === UV_ENFILE ||
    err === UV_ENOENT) {
  process.nextTick(onErrorNT, this, err);
  // ...
} else if (err) {
  // ...
  throw new ErrnoException(err, 'spawn');
}

Only when the errno is one of EACCES / EAGAIN / EMFILE / ENFILE / ENOENT does Node.js route it through process.nextTick into an 'error' event. Anything else gets thrown synchronously, right there. Windows produced ENOENT (on the allow-list, so it went through the event path); Linux produced ENOTDIR (not on the allow-list, so it threw). The same underlying mistake — a cwd that is really a file — ends up delivered in opposite ways purely because of which errno name happened to come back. The code that attaches err.path and err.spawnargs only exists on the 'error'-event path, so a thrown error carries no trace of the executable’s name at all.

Worth noting: the synchronous version, spawnSync, did not show this split at all. For every one of the three errno values tested here (ENOENT, ENOTDIR, EACCES), spawnSync neither threw nor emitted an 'error' event — it returned the failure inside result.error every time. Delivery does not depend on the errno, so it is simpler to work with than the async spawn. That said, only three errno values were checked, so this is not a claim that every possible errno behaves the same way with spawnSync.

shell: true and the messenger switch

One more shape of this problem shows up easily in real code. Passing shell: true to spawn tells Node.js to run the given command through a shell (/bin/sh on Linux, cmd.exe on Windows). So who does ENOENT name in that case?

await run('D', 'definitely-not-a-real-binary-xyz', [],
          { cwd: realDir, shell: true, stdio: 'ignore' });
await run('E', 'echo', ['ok'], { cwd: missingDir, shell: true, stdio: 'ignore' });

D is “a command that does not exist, in a real cwd.” E is “a command that does exist (echo), in a cwd that does not.” On Linux:

D: no error event
  close     : code=127 signal=null

E:
  message   : spawn /bin/sh ENOENT
  code      : ENOENT
  path      : /bin/sh
  close     : code=-2 signal=null

D (the missing command) does not even emit an 'error' event — it simply comes back as exit code 127, the shell’s traditional “command not found” signal. E (the missing cwd) does become ENOENT, and err.path names /bin/sh, not echo. Windows follows the same pattern, naming cmd.exe instead:

D: no error event
  close     : code=1 signal=null

E:
  message   : spawn C:\WINDOWS\system32\cmd.exe ENOENT
  code      : ENOENT
  path      : C:\WINDOWS\system32\cmd.exe
  spawnargs : ["/d","/s","/c","\"echo ok\""]

The instant shell: true enters the picture, err.path stops naming the command you meant to run and starts naming the shell standing in front of it. That cuts both ways, though — it also gives you a diagnostic shortcut: if you see ENOENT with shell: true in play, the problem is not a typo in your command; it is either the cwd or the shell binary itself. A command that genuinely does not exist never registers as a spawn failure at all — it slips out quietly as a shell exit code instead.

What to actually do about it

err.path always names the executable (or the shell), never the cwd. On POSIX, chdir runs before exec, and its failure travels down the same pipe, so the two causes get mixed by the time they reach Node.js. On Windows, there is no separate stage to fail at in the first place, and several distinct errors get rounded down into one errno.

The bigger trap is that the identical failure arrives differently depending on platform: an 'error' event on Windows, a synchronous throw on Linux. A try/catch alone, or an 'error' listener alone, is guaranteed to miss one platform or the other.

So what should you actually write? The most reliable fix is to check that cwd exists — or create it — before calling spawn, rather than trying to reverse-engineer the cause from the error afterward. Verifying the precondition up front is both faster and immune to the platform differences described here. If you do need error handling around spawn itself, set up both a try/catch and an 'error' listener, and where spawnSync is an option, standardizing on its result.error return value sidesteps the whole event-versus-throw question.

One last thing worth keeping in mind: the wording of the error message itself is not trustworthy. As shown above, even Node.js‘s own message — one that reads as “the executable could not be found” — can be produced by a case that was really about the cwd, repeatably. Wrapper libraries built on top of spawn are liable to reformat that message into something even more plausible-sounding and even further from the truth. What is worth trusting is err.code, plus your own explicit assumptions about the cwd and the executable you passed in — not the sentence Node happened to print.

A closing scope note: everything measured here is Windows and Linux. macOS is also POSIX, but it was not tested, and the Linux results here should not be assumed to transfer over automatically. execFile, fork, and third-party wrapper libraries built on top of spawn are outside the scope of this article too — any of them could change how (or whether) these errors reach your code, depending on how they wrap spawn internally.

Primary sources

• Node.js documentation, child_process.spawn() (the cwd option: states that ENOENT fires both when the given path does not exist and when the command does not exist)
• Node.js documentation, the 'error' event (states that the 'error' event fires when the process could not be spawned)
• Node.js source, lib/internal/child_process.js (v22.12.0) (the err.path = this.spawnfile assignment, and the allow-list of errno values routed to the 'error' event versus thrown synchronously)
• libuv source, src/unix/process.c (the order of chdir() and execvp() inside uv__process_child_init)
• libuv source, src/win/process.c (the CreateProcessW call, how cwd is passed in, and the GetLastError() to uv_translate_sys_error() conversion)
• libuv source, src/win/error.c (the list of Windows error codes mapped to UV_ENOENT; no case maps to UV_ENOTDIR)
• Microsoft Learn, CreateProcessW function (the lpCurrentDirectory parameter)