docling-project/docling · error · ValueError

probe_fps must be > 0

Error message

probe_fps must be > 0

What it means

ValueError raised by the scene-detection sampler's __init__ in docling/utils/video_frame_sampling.py when probe_fps is zero or negative. The detector first decodes the video into a downscaled probe stream at probe_fps frames per second to measure frame-difference signals, so a non-positive probe rate is meaningless and would break frame extraction.

Source

Thrown at docling/utils/video_frame_sampling.py:336

       with a prominence criterion — self-calibrating per video, no manual
       threshold needed.
    5. Selects the sharpest frame in a window around each scene midpoint
       as the representative keyframe, avoiding motion-blurred frames.
    """

    def __init__(
        self,
        probe_fps: float = 1.0,
        prominence: float | None = None,
        cuts_per_minute: float | None = None,
        min_scene_duration_seconds: float = 2.0,
        max_frames: int | None = None,
        probe_size: int = 64,
        smooth_window: int = 1,
        sharpness_candidates: int = 5,
    ):
        if probe_fps <= 0:
            raise ValueError("probe_fps must be > 0")
        if prominence is not None and prominence < 0:
            raise ValueError("prominence must be >= 0")
        if min_scene_duration_seconds < 0:
            raise ValueError("min_scene_duration_seconds must be >= 0")
        if max_frames is not None and max_frames <= 0:
            raise ValueError("max_frames must be > 0 when set")
        self.probe_fps = probe_fps
        self.prominence = prominence
        self.cuts_per_minute = cuts_per_minute
        self.min_scene_duration_seconds = min_scene_duration_seconds
        self.max_frames = max_frames
        self.probe_size = probe_size
        self.smooth_window = smooth_window
        self.sharpness_candidates = sharpness_candidates

    def _probe_frames(self, video_path: Path) -> list[tuple[float, Image.Image]]:
        """Extract downscaled RGB probe frames at probe_fps in a single decode pass."""
        return _extract_frames_grid(video_path, self.probe_fps, self.probe_size)

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Pass a positive probe rate; the default probe_fps=1.0 (one probe frame per second) is a sensible baseline.
2. If computing probe_fps from metadata, guard the division: probe_fps = n / duration if duration > 0 else 1.0.
3. Validate the video with ffprobe first when metadata-driven rates come out as 0 (the file may be corrupt or unreadable).

Example fix

# before
probe_fps = num_probes / duration  # duration=0.0 -> ZeroDivisionError / 0
sampler = SceneAwareSampler(probe_fps=probe_fps)

# after
probe_fps = num_probes / duration if duration > 0 else 1.0
sampler = SceneAwareSampler(probe_fps=max(probe_fps, 0.1))

probe_fps = num_probes / duration if duration and duration > 0 else 1.0
if probe_fps <= 0:
    probe_fps = 1.0
sampler = SceneAwareSampler(probe_fps=probe_fps)

When it happens

Trigger: Constructing the scene-detection sampler with probe_fps=0 or a negative value, or with a computed rate such as probe_fps = n / duration where n is 0 or duration is huge relative to n (underflow to 0).

Common situations: Auto-tuning probe rate from video metadata (duration probes returning 0.0 for broken/corrupt files make the division 0); config files where the key was left at 0; passing fps values from a probe tool that reports 0 for variable-frame-rate streams.

Related errors

• prominence must be >= 0
• min_scene_duration_seconds must be >= 0
• interval_seconds must be > 0
• max_frames must be > 0 when set
• Cannot convert Box Note with hash {self.document_hash}: no '

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/dcd13cd1a30790ff. Report an issue: GitHub.