Node.js cannot start the program it was asked to run
Error: spawn convert ENOENTShort 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.
Fix it fast
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)"2Match what you see, then jump to its fix
- 1
command -v prints nothing, even in your own terminalThe program is not installed, or the name is wrongFix - 2
The 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
The 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
Error: 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
spawn ./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
- 1
What does the error look like?
Error: spawn convert ENOENTError: spawn npm ENOENTerrno: -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 convert2Fix
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.jsConfirmed by nodejs.org
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 convert2Fix
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-pagerConfirmed by nodejs.org
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.jsConfirmed by nodejs.org
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 npm2Fix
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.jsConfirmed by nodejs.org
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.sh2Fix
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.sh3Verify
The first line ends in $ with no ^M, and the script starts.
head -n 1 deploy.sh | cat -AConfirmed by man7.org
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
Back end
Application Load Balancer returns 502 for a Node.js target
HTTPCode_ELB_502_Count
An ALB returns 502 when the target gives it something it cannot use: a refused or reset connection, a connection closed mid-request, a bad response, or a header over 32 K.
4 causes, each with a fixBack end
corepack enable fails: permission denied while creating the pnpm link
Internal Error: EACCES: permission denied, symlink '../lib/node_modules/corepack/dist/pnpm.js' -> '/usr/local/bin/pnpm'
corepack enable writes small link files for yarn and pnpm next to your node binary.
2 causes, each with a fixBack end
Create React App says Node is too old, and npm will not run on the new one
npm does not support Node.js v10.19.0
The shell is running an old Node.js that is below the version Create React App needs.
3 causes, each with a fixBack end
firebase deploy cannot load your functions: user code failed to load
Functions codebase could not be analyzed successfully. It may have a syntax or runtime error
The Firebase CLI loads your functions code on your machine before it deploys, to learn which functions exist.
4 causes, each with a fixBack end
firebase deploy stops because the predeploy lint step failed
Error: There was an error deploying functions
The predeploy hook in firebase.json runs npm run lint before every deploy, and a failing hook cancels the deploy.
3 causes, each with a fixBack end
fluent-ffmpeg cannot find the ffmpeg or ffprobe binary
Error: Cannot find ffprobe
fluent-ffmpeg does not bundle ffmpeg.
4 causes, each with a fix