Maaz Zindani

Loading the index…

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

fluent-ffmpeg cannot find the ffmpeg or ffprobe binary

ErrorError: Cannot find ffmpeg

Short answer

fluent-ffmpeg does not bundle ffmpeg. It looks for the binary in the FFMPEG_PATH variable first and then on the PATH of the Node.js process. If neither finds it, you get Cannot find ffmpeg. Install ffmpeg, then give the library the full path to the executable, and do the same for ffprobe.

  • Applies to fluent-ffmpeg 2.1, Node.js 22, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask the same shell that starts your app where ffmpeg and ffprobe are. Empty output means the Node.js process cannot see them either.

    which ffmpeg ffprobe
    node -e "console.log(process.env.FFMPEG_PATH, process.env.FFPROBE_PATH)"
  2. 2Match what you see, then jump to its fix

    1. 1which ffmpeg prints nothing, and the error is Cannot find ffmpegffmpeg is not installed on the machineFix
    2. 2ffmpeg works in your terminal, but the app started by a service manager, an IDE or a Windows shortcut throws Cannot find ffmpegThe binary exists but is not on the PATH of the Node.js processFix
    3. 3FFMPEG_PATH is set, yet the error remainsFFMPEG_PATH points at a folder or at a file that does not existFix
    4. 4Cannot find ffprobe, while plain conversions workffmpeg is found but ffprobe is notFix

What does the error look like?

  • Error: Cannot find ffmpeg
  • Error: Cannot find ffprobe

Cause 1 of 4

ffmpeg is not installed on the machine

1Check

fluent-ffmpeg is only a wrapper that starts the ffmpeg program. It does not install it, so a fresh server or container has nothing to start.

ffmpeg -version

2Fix

Install ffmpeg from your distribution. On Ubuntu and Debian it is a normal package. The README says ffprobe usually comes bundled with ffmpeg, and the library needs both, so check the ffprobe line too.

sudo apt update && sudo apt install -y ffmpeg
which ffmpeg ffprobe

3Verify

Both commands print a path, and the app no longer throws.

ffprobe -version | head -n 1

Confirmed by ffmpeg.org

Did this fix it?

Cause 2 of 4

The binary exists but is not on the PATH of the Node.js process

1Check

The library asks the operating system for ffmpeg on the PATH it inherited. The README says that on Windows ffmpeg and ffprobe are usually not on the PATH, so the paths must be set explicitly.

which ffmpeg
echo $PATH

2Fix

Set the full path to each binary through environment variables before the library runs, or in code with the two setters.

# environment
FFMPEG_PATH=/usr/bin/ffmpeg
FFPROBE_PATH=/usr/bin/ffprobe

// or in code
const ffmpeg = require('fluent-ffmpeg');
ffmpeg.setFfmpegPath('/usr/bin/ffmpeg');
ffmpeg.setFfprobePath('/usr/bin/ffprobe');

3Verify

Run a small probe on any media file. It should print the stream list instead of an error.

node -e "require('fluent-ffmpeg').ffprobe('sample.mp4',(e,d)=>console.log(e||d.streams.length))"

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 3 of 4

FFMPEG_PATH points at a folder or at a file that does not exist

1Check

The README says the value is the full path to the ffmpeg binary. The library checks that this file exists and, if it does not, silently falls back to searching the PATH. A folder, a typo or a path inside another container therefore looks the same as no setting at all.

ls -l "$FFMPEG_PATH"
test -x "$FFMPEG_PATH" && echo executable

2Fix

Point the variable at the executable itself (on Windows, including ffmpeg.exe), not at its directory.

# wrong
FFMPEG_PATH=/usr/local/bin
# right
FFMPEG_PATH=/usr/local/bin/ffmpeg

3Verify

The test command above prints executable, and the app runs a conversion.

test -x "$FFMPEG_PATH" && echo executable

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 4 of 4

ffmpeg is found but ffprobe is not

1Check

Calls such as ffprobe() or anything that reads metadata need the separate ffprobe program. The library looks at FFPROBE_PATH, then the PATH, then the folder that holds the ffmpeg binary. An ffmpeg file copied on its own does not bring ffprobe with it.

which ffprobe
ls "$(dirname "$(which ffmpeg)")"

2Fix

Install the full ffmpeg package, or put ffprobe next to ffmpeg, or set FFPROBE_PATH to its full path.

export FFPROBE_PATH=/usr/bin/ffprobe
# or in code
# ffmpeg.setFfprobePath('/usr/bin/ffprobe');

3Verify

ffprobe runs from the shell and the Node.js call returns metadata.

ffprobe -version | head -n 1

Confirmed by raw.githubusercontent.com

Did this fix it?

How do I stop it coming back?

  • Install ffmpeg in your Dockerfile or provisioning script, and set FFMPEG_PATH and FFPROBE_PATH explicitly so the app never depends on a PATH it did not choose.
  • Fail fast at startup: run ffmpeg -version once when the app boots and stop with a clear message if it is missing.
  • Plan to move off this library: the project is no longer maintained and its README says it no longer works properly with recent ffmpeg versions, so keep an eye on a maintained wrapper or call ffmpeg with child_process.

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.