Common FFmpeg errors and the fix for each

Most FFmpeg errors are one of about a dozen messages, and the table below gives each one with its meaning and its fix. One rule covers nearly all of them. The last line FFmpeg prints is a generic summary, and the cause is named a line or two above it. And if your FFmpeg runs behind an API, check the input URL before the command, because in failed jobs on ours a download that never happened was the more common cause.

The errors, what they mean, and the fix#

Every message here is FFmpeg’s own text, reproduced on FFmpeg 8.0 with a known clip. Where FFmpeg prints two lines, the first one names the cause and the second is the summary most people copy into a search box.

Conversion failed! is never the cause. It is the line FFmpeg prints after something above it went wrong. The same goes for a bare Invalid argument, which FFmpeg attaches to at least six of the failures in this table. Scroll up.

Which messages are Rendobar’s and which are FFmpeg’s#

This post was first written from Rendobar’s failed jobs, and one message dominated them: Invalid argument. Check your FFmpeg flags and values. That sentence is ours, not FFmpeg’s, and the first version of this post presented it as FFmpeg’s text. It was wrong to.

Rendobar’s FFmpeg API rewrites a few FFmpeg messages into a shorter error.message. When stderr contains one of these, the job’s message is replaced:

Anything else comes through as FFmpeg’s own last error line, prefixed with FFmpeg execution failed after Ns:. Error opening output files: Filter not found is one of those, so it is FFmpeg’s text.

The first row is the weak one. FFmpeg says Invalid argument for a -vf overlay, a bad label, an unconnected output, a missing stream, odd dimensions and a bad preset, so the rewritten message cannot tell you which. The specific line is still there. A failed job carries the tail of FFmpeg’s stderr in error.detail, and that is where to read the cause.

Why overlay fails so often#

In our failed jobs, more commands used overlay than used subtitles and drawtext combined. About two thirds of those overlay failures came back as the generic Invalid argument message, and every one that reached FFmpeg ended within 35 ms of the step starting. Nothing gets decoded that fast, so the command never parsed.

The cause is structural. overlay takes two inputs, and -vf only ever sees the first one, so this cannot work however the coordinates are written:

# Fails. -vf has no access to the second input.
ffmpeg -i base.mp4 -i logo.png -vf "overlay=10:10" out.mp4

FFmpeg says so directly, on the line above the summary:

[vf#0:0 @ 0000024cc52df1c0] Simple filtergraph 'overlay=10:10' was expected to have exactly 1 input and 1 output. However, it had 2 input(s) and 1 output(s). Please adjust, or use a complex filtergraph (-filter_complex) instead.
Error opening output file out.mp4.
Error opening output files: Invalid argument

Two inputs means -filter_complex and explicit labels:

# Works.
ffmpeg -i base.mp4 -i logo.png \
  -filter_complex "[0:v][1:v]overlay=W-w-20:H-h-20" \
  -c:a copy out.mp4

[0:v] is the video of the first input and [1:v] the video of the second. W and H are the base dimensions, w and h the overlay’s, so W-w-20 pins it 20 pixels from the right edge. The same rule covers concat, amix, hstack, blend and every transition: more than one input needs -filter_complex. The full set of corner positions, logo sizing and text watermarks is in how to add a watermark with FFmpeg.

Most failed jobs never reached FFmpeg#

When I grouped failed jobs on the Rendobar API by the stage that failed, FFmpeg rejecting the command was not the largest group:

These are all failed jobs in the job archive as of 2026-08-20, across job types, with shares rounded. The traffic is ours, much of it exploratory, so read the order and not the exact proportions. A pipeline running one known-good command against reliable storage will fail less and in different ways.

The download failures each point to a different fix. A 404 means the URL is wrong or the object is gone. A 401 or 403 means the URL needs credentials, which is the usual result of passing a private storage link without signing it. A 429 means the origin rate-limited the fetch, common with sites that were never meant to serve media. A plain fetch failure means DNS or TLS. A presigned URL that worked when you wrote the job and fails on a retry three hours later has expired, and presigned URLs can expire earlier than the expiry you set.

Debugging in the order failures happen#

1. Did the input arrive? Fetch the URL yourself, unauthenticated, from somewhere other than your machine. On our data this settles the largest group.
2. Did it fail at once? A failure before any frame was written is a parse or setup error, so the media content is irrelevant. Read the line above the summary.
3. Does the filter graph parse? Build it one filter at a time, check every label, and use -filter_complex for anything with two inputs.
4. Does your build have the pieces? ffmpeg -filters and ffmpeg -encoders answer in one command.

Only then look at flag values, which is where most people start.

Reading the failure from the API#

A failed Rendobar job returns the stage it died in (failedPhase), the wrapped message, and FFmpeg’s stderr tail. Both tabs below run the same command against an input URL that does not exist, which fails in preparing, before FFmpeg starts.

import { createClient } from "@rendobar/sdk";

const rb = createClient({ apiKey: process.env.RENDOBAR_API_KEY });

// throwOnFailure: false returns the failed job instead of throwing.
const job = await rb.jobs.run(
{
  type: "ffmpeg",
  params: {
    command: "ffmpeg -i https://cdn.rendobar.com/assets/examples/does-not-exist.mp4 -c:v libx264 -t 5 out.mp4",
  },
},
{ throwOnFailure: false },
);

if (job.status === "failed") {
// failedPhase is "preparing" when the input never downloaded and
// "processing" when FFmpeg itself rejected the command.
console.log(job.error.failedPhase, job.error.code);
console.log(job.error.message);
// FFmpeg's own stderr tail, or null when FFmpeg never ran.
console.log(job.error.detail);
}

curl -X POST https://api.rendobar.com/jobs \
-H "Authorization: Bearer $RENDOBAR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "type": "ffmpeg",
  "params": { "command": "ffmpeg -i https://cdn.rendobar.com/assets/examples/does-not-exist.mp4 -c:v libx264 -t 5 out.mp4" }
}'

# Then read error.failedPhase, error.message and error.detail
curl https://api.rendobar.com/jobs/JOB_ID \
-H "Authorization: Bearer $RENDOBAR_API_KEY"

A probe catches the largest failure group at the price of a probe instead of an encode, and validating uploads with ffprobe covers using one as a gate.

My advice is to stop reading FFmpeg errors from the bottom. The last line tells you that something failed, the line above it tells you what, and on an API the URL fails before either.