FFmpeg Debugging & Troubleshooting – Read Logs, Fix Errors Fast

FFmpeg is incredibly powerful, but its error messages can feel like ancient riddles. You paste a command, hit Enter, and get:

Conversion failed!

That's it. No context, no hint—just failure. Or worse, a wall of text with a single line buried in the middle that actually tells you what went wrong. Most tutorials show working examples and never teach you how to fix things when they break.

This guide changes that. You'll learn how to read FFmpeg's language, use the right log levels, decode filtergraph failures, and leverage the FFmpegLab IDE as a real-time linter for your commands.

Key takeaways

-loglevel is your most important debugging tool—know when to use error, warning, verbose, debug, and trace.
Filtergraph errors are the #1 source of failures. Learn to spot "Input pad not connected" vs. "Output pad not labelled".
ffprobe is your friend—always inspect the input before building the command.
FFmpegLab catches syntax errors, validates filter connections, and highlights issues in real time.
Exit codes tell a story: 0 = success, 1 = error, 2 = invalid argument, 64 = usage error.

The Gap: Working Examples vs. Broken Reality

Tutorials are great—until your input file doesn't match the example. The documentation for ffmpeg lists options and flags, but it rarely teaches diagnostic thinking. When the command fails, you're left with a cryptic message and no roadmap.

The gap isn't a lack of information; it's a lack of methodology. This guide gives you a step-by-step approach to troubleshooting any FFmpeg failure.

The Symptom: "Conversion failed!" – Now What?

You see the dreaded error banner. Your instinct might be to copy the error into Google and pray. But before you do, take a breath and follow these steps:

Increase the log level to see more details.
Check the very last error line—FFmpeg usually tells you the specific problem right before exiting.
Verify your inputs using ffprobe.
Simplify the filtergraph—remove filters until it works, then add them back one by one.

Let's dive into each step.

Log Levels – Your First Weapon

The -loglevel (or -v) flag controls how much information FFmpeg prints. Most users stick to the default (info), which hides crucial details.

Level	Flag	When to use
`quiet`	`-loglevel quiet`	Production scripts (no output unless fatal)
`fatal`	`-loglevel fatal`	Only show fatal crashes
`error`	`-loglevel error`	Show errors and fatal messages (good for CI/CD)
`warning`	`-loglevel warning`	Show warnings and above (default for many scripts)
`info`	`-loglevel info`	Default—shows progress, some metadata
`verbose`	`-loglevel verbose`	More details about inputs, outputs, and filter setup
`debug`	`-loglevel debug`	Everything—stream info, frame details, filter negotiation
`trace`	`-loglevel trace`	Insane detail—every frame, every byte (use as last resort)

Pro tip: Start with error if you just want the clean error message. If that's not enough, escalate to verbose to see exactly where FFmpeg fails.

Generated Code Logs Customize

# Verbose logging helps you see exactly where the pipeline breaks
ffmpeg -loglevel verbose -i input.mp4 -vf "crop=100:100" -c:a copy out.mp4

▶

Decoding Filtergraph Errors

Filtergraphs are the most common source of failures. Here's how to decode the three most frequent errors:

1. "Input pad X is not connected"

You're using a filter that requires multiple inputs (like overlay or xfade), but you only linked one stream.

# WRONG – overlay needs two inputs
ffmpeg -i video.mp4 -filter_complex "[0:v]overlay[out]" -map "[out]" out.mp4
# Error: Input pad 1 is not connected

2. "Output pad Y is not labelled"

You split a stream but forgot to name one of the outputs.

# WRONG – second output [b] is not labelled
ffmpeg -i video.mp4 -vf "split [a]; [a] crop=100:100 [c]" out.mp4
# Error: Output pad 1 is not labelled

3. "Filter X has unset parameters"

You forgot a required parameter (like w or h in crop).

# WRONG – crop needs w and h
ffmpeg -i video.mp4 -vf "crop=" out.mp4
# Error: Filter crop has unset parameters

FFmpegLab's visual filtergraph editor solves this by highlighting unconnected pads and showing missing parameters before you even run the command.

Stream Mapping & Format Woes

-map syntax is notoriously tricky. The golden rules:

-map 0:v → take video streams from input 0
-map 0:a → take audio streams from input 0
-map 0:s → take subtitle streams from input 0
-map 0:v:0 → take the first video stream from input 0

Container constraints: Not every format supports every codec. MP4 can contain H.264, HEVC, and AAC, but cannot contain FLAC or DTS without issues. MOV supports ProRes, but not VP9. Always check ffprobe to see what's inside.

Generated Code Logs Customize

# Explicitly map video and audio to avoid "Stream specifier" errors
ffmpeg -i input.mkv -map 0:v:0 -map 0:a:0 -c:v libx264 -c:a aac output.mp4

▶

FFprobe – The Diagnostic Swiss Army Knife

Before you build a complex command, inspect your input. FFprobe gives you a complete picture of what you're working with.

# List all streams with codec, resolution, bitrate, and metadata
ffprobe -v error -show_streams input.mov

# Check if your file actually has audio (surprisingly common issue)
ffprobe -v error -select_streams a -show_entries stream=codec_name -of default=noprint_wrappers=1 input.mp4

# Print the exact frame count and duration
ffprobe -v error -show_entries format=duration,size -of default=noprint_wrappers=1 input.mp4

If you get errors during encoding, always check your input with ffprobe first. It answers critical questions: Is there a video stream? What's the pixel format? Is the audio codec compatible with my output container?

Common Error Patterns & Their Fixes

Error Message	Likely Cause	Fix
`Protocol not found`	You typed a file path without quoting spaces	Wrap paths in quotes: `"my video file.mp4"`
`Invalid data found when processing input`	Input file is corrupted or incomplete	Use `-err_detect explode` to see more details
`Pixel format not supported`	Encoder doesn't support 10-bit YUV	Add `-pix_fmt yuv420p` for 8-bit output
`Decoder not found`	FFmpeg build missing a codec	Check available codecs: `ffmpeg -codecs \| grep your_codec`
`Frame size not set`	Raw video input needs dimensions	Specify `-video_size` and `-pixel_format`
`Bitrate not specified`	VBR encoding without target bitrate	Add `-b:v 5M` or use `-crf`

Understanding Exit Codes

In scripting, FFmpeg's exit code tells you exactly what happened:

0 – Success
1 – General error (frame encoding failed, invalid parameter, file not found)
2 – Invalid argument (wrong flag, missing value)
64 – Usage error (wrong command syntax)
126 – Command not executable (permissions issue)
127 – Command not found

In a bash script, you can check the exit code with echo $? immediately after running FFmpeg.

Debug Smarter with the FFmpegLab IDE

The FFmpegLab editor is built for this. Instead of running the command blindly, you get:

Live linting – Syntax errors are highlighted as you type.
Filtergraph visualization – See how pads are connected and instantly spot unlinked inputs.
Context-aware logs – The Logs panel filters out noise and shows you the relevant error.
Parameter suggestions – Hover over a filter to see its required parameters.

Here's a classic mistake—trying to use overlay with only one input—and how the FFmpegLab IDE catches it before you waste time waiting for the encode to fail.

Generated Code Logs (⚠️ Error) Customize

          [error] Filter overlay has input pad 1 not connected!

          Hint: overlay requires two input streams. Example: [0:v][1:v]overlay

ffmpeg -i video.mp4 -filter_complex "[0:v]overlay[out]" -map "[out]" out.mp4

▶

Notice how the IDE doesn't just show the command—it understands the filtergraph and warns you about the missing connection before you press run. That's the power of integrating a linter directly into the editor.

You can also toggle log levels directly in the UI, switch between verbose and quiet modes, and see exactly how the filtergraph interprets your streams.

Frequently Asked Questions (FAQ)

What does "Connection to pad not supported" mean?

This usually means you're trying to connect a video filter to an audio stream or vice versa. Check that you're linking the correct stream types (:v for video, :a for audio) in your filtergraph.

Why does my command work on one file but fail on another?

Input files can have different codecs, pixel formats, or stream counts. Always inspect your input with ffprobe before running the command. The FFmpegLab IDE automatically shows you the stream list when you load a file.

What's the best log level for debugging filtergraph errors?

Start with -loglevel verbose. It shows you exactly how FFmpeg negotiates filter parameters and which pads are being connected. If that's not enough, escalate to debug, but be prepared for a lot of text.

How do I check which codecs my FFmpeg build supports?

Run ffmpeg -codecs for a full list of supported encoders and decoders. For specific codec details, use ffmpeg -h encoder=libx264 to see all available options for that encoder.

Final Word

Debugging FFmpeg isn't about memorizing every error—it's about having a method. Start with the right log level, inspect your inputs with ffprobe, decode the filtergraph step by step, and use tools like the FFmpegLab IDE to get instant feedback.

The next time you see "Conversion failed!", don't panic. Open the logs, read the last error, check your filter connections, and fix it. You now have the toolkit to troubleshoot anything FFmpeg throws at you.