Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Node.js cannot start the program it was asked to run

ErrorError: spawn convert ENOENT

Short answer

spawn ENOENT means the operating system could not start the file Node asked for. Either the command does not exist where the process looks, the cwd you passed does not exist, or the file is a Windows .cmd script or a shell script whose interpreter is missing. The program name in the message is the one to check.

  • Applies to Node.js 22 and 24, Ubuntu 24.04, Windows 11
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Take the name from the message and ask the same machine, as the same user, whether it can find it. Then print the working directory and PATH that the Node process itself sees, because that is what spawn uses.

    command -v convert
    node -e "console.log(process.cwd()); console.log(process.env.PATH)"
  2. 2Match what you see, then jump to its fix

    1. 1command -v prints nothing, even in your own terminalThe program is not installed, or the name is wrongFix
    2. 2The program starts in your terminal, but spawn fails when Node runs from a service, cron, an editor or CIThe Node process has a different PATH than your terminalFix
    3. 3The program exists on PATH, but the error appears only when a cwd is set (a build folder, a temp folder, a user upload folder)The cwd option points to a folder that does not existFix
    4. 4Error: spawn npm ENOENT (or npx, yarn, a .bat tool) on Windows, while the same call works on Linux and macOSOn Windows the target is a .cmd or .bat file such as npmFix
    5. 5spawn ./deploy.sh ENOENT although ls shows the file, often after the file was edited on WindowsA script starts, but the interpreter on its first line is missingFix

What does the error look like?

  • Error: spawn convert ENOENT
  • Error: spawn npm ENOENT
  • errno: -2, code: 'ENOENT', syscall: 'spawn convert', path: 'convert'

Cause 1 of 5

The program is not installed, or the name is wrong

1Check

spawn does not run a shell, so it needs the real program name, not an alias or a shell function. A name that works in your prompt because of an alias still fails here.

command -v convert
type convert

2Fix

Install the program, or correct the name in the spawn call. Pass arguments as an array, not as part of the command string.

const { spawn } = require('node:child_process');
const child = spawn('convert', ['in.png', 'out.jpg']);
child.on('error', (err) => console.error('could not start:', err.code));

3Verify

The error event no longer fires and the program runs.

node convert.js

Confirmed by nodejs.org

Did this fix it?

Cause 2 of 5

The Node process has a different PATH than your terminal

1Check

A child gets the environment of the process that starts it (env defaults to process.env). A service manager, cron job or IDE often starts Node with a short PATH that lacks the folder where the program lives. Print it from inside the failing process.

console.log(process.env.PATH);
// and the full path of the program in your terminal:
// command -v convert

2Fix

Call the program by its absolute path, or pass the PATH you need in the env option.

spawn('/usr/bin/convert', ['in.png', 'out.jpg']);

spawn('convert', ['in.png', 'out.jpg'], {
  env: { ...process.env, PATH: `/usr/local/bin:${process.env.PATH}` },
});

3Verify

The same code started by the service now runs the program.

sudo systemctl restart my-app && journalctl -u my-app -n 20 --no-pager

Confirmed by nodejs.org

Did this fix it?

Cause 3 of 5

The cwd option points to a folder that does not exist

1Check

Node reports the same ENOENT when the cwd path is missing, so the message blames the command although the folder is wrong. Check the folder just before spawning.

const fs = require('node:fs');
console.log(fs.existsSync(opts.cwd), opts.cwd);

2Fix

Create the folder first, or use a path that is always there. Resolve relative paths against a fixed base such as __dirname, not against wherever the process was started.

const path = require('node:path');
const fs = require('node:fs');
const cwd = path.join(__dirname, 'build');
fs.mkdirSync(cwd, { recursive: true });
spawn('make', [], { cwd });

3Verify

The command starts inside the folder.

node run-build.js

Confirmed by nodejs.org

Did this fix it?

Cause 4 of 5

On Windows the target is a .cmd or .bat file such as npm

1Check

On Windows npm and npx are .cmd scripts, not programs, and spawn without a shell looks for a real executable. Node's documentation says .bat and .cmd files cannot be started with execFile, and lists the working ways.

where npm

2Fix

Run it through cmd.exe, or use exec for a single command line. Quote a script path that contains spaces.

const { exec, spawn } = require('node:child_process');

spawn('cmd.exe', ['/c', 'npm', 'run', 'build']);

exec('npm run build', (err, stdout, stderr) => { /* ... */ });

3Verify

The command starts on Windows and still works on Linux when you run the same file there.

node run-build.js

Confirmed by nodejs.org

Did this fix it?

Cause 5 of 5

A script starts, but the interpreter on its first line is missing

1Check

When the kernel starts a script it needs the program named after #! to exist. If that line ends with a Windows carriage return, the interpreter name includes it and cannot be found, so the error names the script, not the interpreter. Show the first line with hidden characters.

head -n 1 deploy.sh | cat -A
ls -l deploy.sh

2Fix

Remove the carriage returns, use an interpreter path that exists on this machine, and make the file executable.

sed -i 's/\r$//' deploy.sh
chmod +x deploy.sh

3Verify

The first line ends in $ with no ^M, and the script starts.

head -n 1 deploy.sh | cat -A

Confirmed by man7.org

Did this fix it?

How do I stop it coming back?

  • Always attach an 'error' listener to the child; without one, the failure is thrown as an uncaught exception.
  • Use absolute paths for programs your service depends on, and set cwd from a fixed base path.
  • Keep shell scripts on LF line endings (a .gitattributes rule for *.sh does it).
  • Check the program's version at startup and fail with a clear message if it is missing.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.