FFmpeg Error Messages, Not Exit Codes, Tell You What to Retry

Your worker ran ffmpeg, the process exited non-zero, and your queue put the job back in line to fail again. Conventional wisdom says check the exit code and retry the failures, which works for most command-line tools. FFmpeg isn't most tools: it exits with code 1 for a corrupt upload, a filter-graph typo, and a full disk alike, so your retry loop keeps re-running jobs that can never succeed.

Quick answer: FFmpeg error messages are diagnosed from stderr, not the exit code, because FFmpeg returns 1 for nearly every failure. Match the exact stderr string and sort it into three classes: bad input (moov atom not found, Invalid data found when processing input), rejected at ingest; bad command (height not divisible by 2, Unknown encoder, matches no streams), fixed and never retried; and resource exhaustion (No space left on device, exit 137 from the OOM killer, network timeouts), the only class worth retrying. If you'd rather not maintain that classifier, FFmpeg Micro runs the job and returns a structured status instead of a stderr dump.

Every FFmpeg error string, what causes it, and whether to retry

The table is keyed on the literal text FFmpeg prints, the only reliable identifier you get. Each row gives the cause behind that string in a pipeline and what your queue should do.

Four of these get their own walkthrough here: moov atom not found, height not divisible by 2, timestamp and sync drift, and the normalize-then-copy fix for concat failures.

FFmpeg exit codes carry almost no signal

FFmpeg exits 0 on success and 1 on nearly every failure: broken file, bad flag, full disk. Other values turn up in the wild (Transloadit's community has a thread about exit code 8), so the number is worse than useless: you can't enumerate it or map it to an action.

Codes above 128 aren't from FFmpeg. Your shell reports 137 for SIGKILL (128 + 9), the OOM killer on a memory-limited container, and 143 for SIGTERM (128 + 15), usually your orchestrator hitting a timeout. Special-case those two because FFmpeg never printed anything.

Treat the exit code as a boolean. Everything else lives in stderr.

Parse stderr and classify into three buckets

Run FFmpeg with -hide_banner -loglevel error so stderr carries diagnosis instead of build configuration and a progress counter, then match the tail against three ordered pattern sets:

import re
import subprocess

REJECT = (r"moov atom not found|Invalid data found when processing input|"
          r"could not find codec parameters|Invalid NAL unit size")

BAD_COMMAND = (r"not divisible by 2|Unknown encoder|Unrecognized option|"
               r"matches no streams|Could not find tag for codec|"
               r"Unable to find a suitable output format|"
               r"Automatic encoder selection failed|Error initializing")

TRANSIENT = (r"No space left on device|Cannot allocate memory|"
             r"Connection timed out|Server returned 5\d\d|Input/output error")

def run(cmd):
    p = subprocess.run(cmd, capture_output=True, text=True)
    tail = "\n".join(p.stderr.strip().splitlines()[-40:])
    if p.returncode == 0:
        return "ok", tail
    if p.returncode in (137, 143):          # SIGKILL / SIGTERM
        return "transient", tail
    for label, pattern in (("transient", TRANSIENT),
                           ("reject", REJECT),
                           ("bad_command", BAD_COMMAND)):
        if re.search(pattern, tail):
            return label, tail
    return "unknown", tail

Only transient goes back on the queue. reject fails the job immediately and tells the uploader what's wrong with their file. bad_command pages you, because a retry reproduces it exactly. unknown gets logged with the full tail and reviewed weekly; that's how the pattern lists grow.

Order matters. Check transient first: a job killed mid-write leaves a truncated output that a later probe reads as bad input, and you'd reject a file that was fine.

Exit code 0 is not proof the output is good

FFmpeg exits 0 while writing files that are wrong. A -map 0:a? that matched nothing yields a silent video. Broken source timestamps yield drifting audio. A filter that dropped frames prints a warning. All three exit 0.

Probe the output before marking the job complete:

ffprobe -v error -of json \
  -show_entries format=duration,size \
  -show_entries stream=codec_type,codec_name,nb_frames \
  out.mp4

Assert what you expected: duration within a second of the input's, stream count matching, nb_frames not zero. That check catches more real breakage than stderr parsing does, because the failures that reach your users are the ones FFmpeg didn't consider failures.

Warnings your pipeline probably treats as failures

FFmpeg writes its progress counter to stderr, so non-empty stderr is not a failure signal, and a check shaped like if stderr: raise fails every successful job you run. That's the most common bug in homegrown FFmpeg wrappers. Messages that read like errors but aren't:

To stop on conditions FFmpeg would otherwise survive, add -xerror. For a failure you can't reproduce, add -report, which writes a full debug-level log to ffmpeg-YYYYMMDD-HHMMSS.log in the working directory, including the exact command line and every decoder decision.

Common pitfalls when handling FFmpeg errors at scale

The patterns that bite hardest aren't in the table, they're in how the surrounding system reads it.

When to stop parsing stderr

If you run a handful of conversions a week, skip all of this and read the log when something breaks. The classifier earns its keep around a few hundred jobs a day, when nobody has time to read stderr by hand and the retry queue costs real money.

Past that you're maintaining a media microservice: the FFmpeg build, the temp volumes, the memory limits, the pattern lists that go stale on every upgrade ("Non-monotonous" became "Non-monotonic" in a recent release, and every regex written against the old spelling went quiet). That's the argument for sending the job somewhere else. FFmpeg Micro takes the job over its REST API, runs it with no servers for you to size, and returns a job status you can branch on instead of a stderr dump; the error semantics are in the docs, and the same jobs work from n8n, Make, Zapier, or an AI agent over MCP. If you'd rather keep FFmpeg in-house, the honest comparison is a self-hosted container, whose running cost is mostly your time.

FAQ

What does "Invalid data found when processing input" mean in FFmpeg?

"Invalid data found when processing input" means FFmpeg couldn't identify a container or codec in the bytes it was given. In a pipeline the file usually isn't video at all: an HTML or JSON error body saved with a .mp4 extension, a zero-byte object, or an empty pipe:0. Check the first bytes and the length before blaming the codec.

Which FFmpeg errors are safe to retry?

Only resource-exhaustion and network failures are safe to retry: No space left on device, Cannot allocate memory, exit 137 from the OOM killer, connection timeouts, and 5xx responses from a remote input URL. Bad input and bad commands fail identically every attempt, so retrying wastes compute and delays the alert you need.

Does FFmpeg exit code 1 mean the output file is unusable?

FFmpeg exit code 1 means the run didn't finish, so delete any output it left behind rather than inspecting it. The dangerous case runs the other way: FFmpeg exits 0 while producing a video with no audio track, a wrong duration, or dropped frames, which is why you should ffprobe every output before marking a job complete.

Why does my pipeline hit FFmpeg errors that never happen on my laptop?

Pipeline-only FFmpeg errors usually come from three differences: the server's build lacks encoders your local install has, the container has a memory ceiling your laptop doesn't, and production input is real user uploads, not your clean test clip. Run ffmpeg -version and ffmpeg -encoders on the actual worker before debugging anything else.

Point your next failing job at the API instead of a worker you babysit, and compare a structured job status to a stderr tail. Sign up free and run it on the file that's been breaking your queue.