unslothai/unsloth · error · ValueError

That reference video decoded to no frames.

Error message

That reference video decoded to no frames.

What it means

After the decode loop over a reference video, decoded_count == 0 means PyAV iterated the container without yielding a single frame, so the code raises ValueError instead of dividing by source_fps on a phantom duration. This is separate from the no-video-track error (513): here the track exists but produces nothing, e.g. headers-only or unparseable-payload files.

Source

Thrown at studio/backend/core/inference/video_minimax_h3.py:419

                raise ValueError(
                    f"MiniMax-H3 reference videos run {H3_REF_VIDEO_MIN_SECONDS:g} to "
                    f"{H3_REF_VIDEO_MAX_SECONDS:g} seconds; this one is longer than "
                    f"{H3_REF_VIDEO_MAX_SECONDS:g}s. Trim it first."
                )
            target_source = int(next_target * source_fps / H3_FPS)
            if target_source > source_index:
                continue
            image = frame.to_image().convert("RGB")
            if fitted_size is None:
                fitted_size = h3_reference_frame_size(*image.size)
            if image.size != fitted_size:
                image = image.resize(fitted_size, Image.LANCZOS)
            while int(next_target * source_fps / H3_FPS) <= source_index:
                frames.append(image)
                next_target += 1

    if decoded_count == 0:
        raise ValueError("That reference video decoded to no frames.")
    duration = decoded_count / source_fps
    if duration + 1e-6 < H3_REF_VIDEO_MIN_SECONDS:
        raise ValueError(
            f"MiniMax-H3 reference videos run {H3_REF_VIDEO_MIN_SECONDS:g} to "
            f"{H3_REF_VIDEO_MAX_SECONDS:g} seconds; this one is {duration:.1f}s."
        )
    frames = frames[: int(round(duration * H3_FPS))]

    waveform, sample_rate = (None, None)
    with av.open(io.BytesIO(blob)) as container:
        if container.streams.audio:
            waveform, sample_rate = _decode_audio_stream(container, np)
    return frames, waveform, sample_rate


def decode_h3_reference_audio(blob: bytes) -> tuple[Any, int]:
    """Decode one uploaded audio file to a float32 ``(samples, channels)`` waveform + its rate."""
    import io

View on GitHub (pinned to 203007d190)

Solutions

  1. Re-export or re-record the file (ffmpeg -i in.mp4 -c:v libx264 ref.mp4 rewrites a clean container and will fail loudly on truly dead sources).
  2. Validate decodability before upload: ffmpeg -v error -i ref.mp4 -f null -.
  3. Reject zero-frame files at the API boundary.

Example fix

# before: headers-only upload -> ValueError('decoded to no frames')
upload_reference(blob=truncated_bytes)

# after: local sanity check before upload
import subprocess
ok = subprocess.run(["ffmpeg", "-v", "error", "-i", "ref.mp4", "-f", "null", "-"]).returncode == 0
Defensive patterns

Strategy: validation

Validate before calling

import av, io

def yields_frames(blob: bytes) -> bool:
    with av.open(io.BytesIO(blob)) as c:
        if not c.streams.video:
            return False
        return next(iter(c.decode(video=0)), None) is not None

Try / catch

try:
    frames, wf, sr = decode_h3_reference_video(blob)
except ValueError as e:
    if str(e) == "That reference video decoded to no frames.":
        return HTTPException(400, "file has a video track but no frames; re-export it")
    raise

Prevention

When it happens

Trigger: A video stream with zero decodable frames (container finalized after an interrupted write); a stream whose packets all fail to decode; files crafted with a video track header but no payloads.

Common situations: Interrupted uploads leaving truncated files; camera/screen-recorder stub files; corrupt transfers that preserve headers.

Related errors

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/a6ba4fa4c74eec89. Report an issue: GitHub.