Maaz Zindani

Loading the index…

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

Node.js child_process fails with spawn EACCES

ErrorError: spawn EACCES

Short answer

EACCES from spawn means the operating system refused to run the file you named. It comes from execve, not from your port or your code. The file has no execute permission, a folder in its path cannot be entered, the disk is mounted noexec, or the path is not a regular file. namei shows which one.

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

Fix it fast

  1. 1Find out which cause you have

    Print the mode and owner of every folder and file on the path of the program you spawn. The first entry without the needed x bit is the cause. Replace the path with the one in your spawn call.

    namei -l /srv/app/bin/convert.sh
  2. 2Match what you see, then jump to its fix

    1. 1namei shows -rw-r--r-- on the last entry (no x anywhere)The file has no execute permissionFix
    2. 2namei shows a directory without x for the user or group that runs Node.js, for example drwx------ owned by rootA folder on the path cannot be entered by the Node.js userFix
    3. 3The file has x bits, the whole path is open, and it still fails. The file lives under /tmp, a USB or network mount, or a Docker volumeThe disk is mounted with noexecFix
    4. 4namei ends on a directory (the first letter of the mode is d), for example a variable that holds a folder instead of the binary inside itThe path you spawn is a folder or another non-regular fileFix

What does the error look like?

  • Error: spawn EACCES
  • Error: spawn /srv/app/bin/convert.sh EACCES

Cause 1 of 4

The file has no execute permission

1Check

The Linux execve manual lists a missing execute permission on the file as one cause of EACCES. Files that were unzipped, copied from Windows or created by a build step often lose the x bit.

ls -l /srv/app/bin/convert.sh

2Fix

Add execute permission for the owner (or for everyone with a+x if the process runs as another user).

chmod u+x /srv/app/bin/convert.sh

3Verify

Run the file directly in a shell as the same user that runs Node.js, then repeat the spawn.

/srv/app/bin/convert.sh --version
node -e "require('node:child_process').spawn('/srv/app/bin/convert.sh', ['--version'], { stdio: 'inherit' })"

Confirmed by man7.org

Did this fix it?

Cause 2 of 4

A folder on the path cannot be entered by the Node.js user

1Check

The execve manual says search permission must exist on every component of the path prefix. A file that is itself executable still fails when one parent folder is closed to the user.

ps -o user= -p $(pgrep -n node)
namei -l /srv/app/bin/convert.sh

2Fix

Give the user search permission on the folder that blocks it, or move the program to a path the service user can reach.

chmod o+x /srv/app

3Verify

Run namei again as the service user: every line should show x for that user.

sudo -u www-data namei -l /srv/app/bin/convert.sh

Confirmed by man7.org

Did this fix it?

Cause 3 of 4

The disk is mounted with noexec

1Check

The mount manual says noexec forbids direct execution of binaries on that filesystem; execve reports EACCES for it. List the mount options for the folder.

findmnt -T /tmp -o TARGET,VFS-OPTIONS,FS-OPTIONS

2Fix

Run the program from a filesystem without noexec. Remounting a system folder with exec is a security change, so move the file first (for example to /opt/app/bin) and only remount if you own that decision.

sudo mkdir -p /opt/app/bin
sudo cp /tmp/convert.sh /opt/app/bin/
sudo chmod 755 /opt/app/bin/convert.sh

3Verify

findmnt for the new location must not list noexec.

findmnt -T /opt/app/bin -o TARGET,VFS-OPTIONS

Confirmed by man7.org

Did this fix it?

Cause 4 of 4

The path you spawn is a folder or another non-regular file

1Check

The execve manual lists a target that is not a regular file as a cause of EACCES. Print the value your code passes and look at its type.

console.log(JSON.stringify(cmd));
// then in a shell:
ls -ld "$CMD_PATH"

2Fix

Point the command at the executable inside the folder, or pass only the program name and let the folder be the cwd option.

const { spawn } = require('node:child_process');
spawn('/srv/app/bin/convert.sh', ['--version'], { cwd: '/srv/app' });

3Verify

The child starts and the 'error' event does not fire.

const child = spawn('/srv/app/bin/convert.sh', ['--version']);
child.on('error', (e) => console.error('spawn failed', e.code));
child.on('spawn', () => console.log('started'));

Confirmed by man7.org

Did this fix it?

How do I stop it coming back?

  • Commit scripts with the execute bit (git update-index --chmod=+x) so a fresh checkout keeps it.
  • Always listen for the 'error' event on the child, because a failed spawn is reported there and not in your callback.
  • Keep programs the service runs in /opt or /usr/local/bin, not in /tmp or on removable mounts.
  • Run the service as one named user and test paths as that user with sudo -u.

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.