Fix Error: spawn /usr/bin/ffmpeg ENOENT in Node.js

This error means Node.js tried to spawn a child process for a binary that does not exist at the specified path. The executable is either not installed, not in the system PATH, or the path is incorrect. Fix it by installing the required binary and verifying its path with which or where.

Reading the Stack Trace

Here's what each line means:

• at ChildProcess._handle.onexit (node:internal/child_process:284:19): The child process handle exited with an ENOENT error because the operating system could not find the specified executable.
• at convertVideo (src/services/mediaService.js:23:18): Your media service spawns ffmpeg on line 23 but the binary is not installed or not at the expected path.
• at MediaController.transcode (src/controllers/mediaController.js:14:22): The controller triggers the transcoding operation that depends on the external binary.

Common Causes

const { spawn } = require('child_process');
const proc = spawn('/usr/bin/ffmpeg', ['-i', input, output]);
// ffmpeg is not installed

const proc = spawn('/usr/local/bin/ffmpeg', args);
// On this system ffmpeg is at /usr/bin/ffmpeg

spawn('ffmpeg -i input.mp4 output.webm'); // Should use array args

The Fix

Use which to dynamically find the binary path instead of hardcoding it. Handle the 'error' event on the spawned process to catch ENOENT and provide a helpful message about installing the missing dependency.

const { spawn } = require('child_process');

function convertVideo(input, output) {
  const proc = spawn('/usr/bin/ffmpeg', ['-i', input, output]);
  return new Promise((resolve, reject) => {
    proc.on('close', (code) => code === 0 ? resolve() : reject(new Error(`ffmpeg exited with ${code}`)));
  });
}

const { spawn, execSync } = require('child_process');

function findBinary(name) {
  try {
    return execSync(`which ${name}`, { encoding: 'utf8' }).trim();
  } catch {
    throw new Error(`Required binary '${name}' not found. Install it with: apt-get install ${name}`);
  }
}

function convertVideo(input, output) {
  const ffmpegPath = findBinary('ffmpeg');
  const proc = spawn(ffmpegPath, ['-i', input, output]);

  return new Promise((resolve, reject) => {
    proc.on('error', (err) => reject(new Error(`Failed to start ffmpeg: ${err.message}`)));
    proc.on('close', (code) => code === 0 ? resolve() : reject(new Error(`ffmpeg exited with code ${code}`)));
  });
}

Testing the Fix

const { convertVideo, findBinary } = require('./mediaService');
const child_process = require('child_process');

jest.mock('child_process');

describe('convertVideo', () => {
  it('throws when ffmpeg is not installed', () => {
    child_process.execSync.mockImplementation(() => { throw new Error(); });
    expect(() => findBinary('ffmpeg')).toThrow("Required binary 'ffmpeg' not found");
  });

  it('resolves when ffmpeg exits with code 0', async () => {
    child_process.execSync.mockReturnValue('/usr/bin/ffmpeg\n');
    const mockProc = { on: jest.fn() };
    child_process.spawn.mockReturnValue(mockProc);
    const promise = convertVideo('in.mp4', 'out.webm');
    const closeHandler = mockProc.on.mock.calls.find(c => c[0] === 'close')[1];
    closeHandler(0);
    await expect(promise).resolves.toBeUndefined();
  });
});

Run your tests:

npm test

Pushing Through CI/CD

git checkout -b fix/nodejs-child-process-enoent,git add src/services/mediaService.js src/services/__tests__/mediaService.test.js,git commit -m "fix: dynamically resolve binary path and handle spawn errors",git push origin fix/nodejs-child-process-enoent

Your CI config should look something like this:

name: CI
on:
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: sudo apt-get update && sudo apt-get install -y ffmpeg
      - run: npm ci
      - run: npm test -- --coverage

The Full Manual Process: 18 Steps

Here's every step you just went through to fix this one bug:

1. Notice the error alert or see it in your monitoring tool
2. Open the error dashboard and read the stack trace
3. Identify the file and line number from the stack trace
4. Open your IDE and navigate to the file
5. Read the surrounding code to understand context
6. Reproduce the error locally
7. Identify the root cause
8. Write the fix
9. Run the test suite locally
10. Fix any failing tests
11. Write new tests covering the edge case
12. Run the full test suite again
13. Create a new git branch
14. Commit and push your changes
15. Open a pull request
16. Wait for code review
17. Merge and deploy to production
18. Monitor production to confirm the error is resolved

Total time: 30-60 minutes. For one bug.

npm install bugstack-sdk

const { initBugStack } = require('bugstack-sdk')

initBugStack({ apiKey: process.env.BUGSTACK_API_KEY })

Deploying the Fix (Manual Path)

1. Install the required binary on the target system or add it to the Dockerfile.
2. Update code to dynamically locate the binary and handle errors.
3. Run tests locally to verify the fix.
4. Open a pull request and wait for CI.
5. Merge and verify the binary is available in the deployment environment.

Frequently Asked Questions