Enable FFprobe Debug Logs to Fix Failing Streams

Troubleshooting a failing media stream requires deep visibility into connection handshakes, packet transfers, and demuxing errors. This guide explains how to configure ffprobe to output granular debugging logs, write diagnostic output to external files, and identify underlying stream failures such as protocol timeouts, codec negotiation mismatches, and corrupt transport streams.

The Essential FFprobe Debugging Flags

By default, ffprobe suppresses detailed operational logs to keep output readable. You can change this behavior using the -loglevel (or -v) flag.

To generate detailed diagnostic messages, use either debug or trace:

  • debug: Shows detailed connection events, demuxer decisions, codec parameters, and internal library warnings.
  • trace: The highest possible verbosity level. It logs every packet, header, and low-level socket transaction.

Basic Debug Command

ffprobe -v debug "https://example.com/live/stream.m3u8"

Maximum Verbosity with Trace

ffprobe -v trace "rtmp://example.com/live/stream"

Saving Debug Logs to a File

Because ffprobe writes its log messages to standard error (stderr), standard redirection (>) will only capture the structural media output (such as JSON or XML). To capture the debug logs, redirect stderr to a file using 2>.

ffprobe -v debug -i "https://example.com/live/stream.m3u8" 2> ffprobe_debug.log

Alternatively, use the -report flag. This built-in FFmpeg mechanism automatically writes a complete diagnostic log file in the current working directory with a timestamped filename:

ffprobe -report -i "https://example.com/live/stream.m3u8"

Enhancing Stream Diagnostics

When streams fail intermittently or hang during probing, standard timeouts and probe sizes might terminate the process before sufficient data arrives. Combine logging with these flags to isolate the issue:

1. Unmask Demuxing and Container Errors

Force ffprobe to report container-level failures and read errors explicitly:

ffprobe -v debug -show_error -i "rtsp://camera.local:554/live" 2> debug.log

2. Increase Probe Size and Duration

If a stream has sparse keyframes or delayed audio tracks, ffprobe may time out before identifying streams. Increase analysis limits:

ffprobe -v debug -analyzeduration 10000000 -probesize 10000000 -i "https://example.com/stream.ts" 2> debug.log

3. Inspect Packet-Level Failures

To check if packets arrive out of order or with corrupt timestamps (PTS/DTS):

ffprobe -v debug -show_packets -i "https://example.com/live/stream.m3u8" 2> packets_debug.log

What to Look for in the Logs

When reviewing the resulting log file, search for the following common indicators:

  • HTTP/Network Errors (http, tcp, tls): Look for HTTP error 403 Forbidden, Connection refused, or TLS handshake failures near the top of the file.
  • Timeout Errors (rw_timeout, Operation not permitted): Indicates network dropouts, firewall blocks, or unresponsive origins.
  • HLS/DASH Playlist Parser Warnings: Messages such as Failed to open segment or Non-monotonous DTS in output stream point to manifest generation issues or segment delivery latency.
  • Missing Codec Parameters: Lines showing Could not find codec parameters for stream indicate that the initialization data (such as SPS/PPS for H.264/H.265) was missing or unreadable within the probe threshold.