invoke-ai/InvokeAI · error · ValueError

No frames decoded from {video_path}

Error message

No frames decoded from {video_path}

What it means

Raised by the video decode worker subprocess when OpenCV (cv2.VideoCapture) opened the file but returned zero decodable frames for the whole stream. It signals that the container exists and opens, but no image data could be produced — typically a codec issue or an empty/corrupt stream. The worker emits this instead of silently returning an empty frame list so the parent knows decoding truly failed.

Source

Thrown at invokeai/app/util/video_decode_worker.py:255

        return

    import cv2

    capture = cv2.VideoCapture(str(video_path))
    if not capture.isOpened():
        capture.release()
        raise FileNotFoundError(f"Unable to open video at {video_path}")
    try:
        while True:
            ok, frame_bgr = capture.read()
            if not ok or frame_bgr is None:
                break
            _emit_stream_frame(cv2.cvtColor(frame_bgr, cv2.COLOR_BGR2RGB))
            emitted = True
    finally:
        capture.release()
    if not emitted:
        raise ValueError(f"No frames decoded from {video_path}")


def main(argv: list[str]) -> int:
    try:
        _limit_worker_memory()
        command = argv[1]
        if command == "stream":
            _assert_decodable_dims(Path(argv[2]))
            _stream(Path(argv[2]))
        elif command == "probe":
            width, height, duration, fps, codec = _probe(Path(argv[2]))
            print(json.dumps({"width": width, "height": height, "duration": duration, "fps": fps, "codec": codec}))
        elif command == "frame":
            _assert_decodable_dims(Path(argv[2]))
            image = _extract_frame(Path(argv[2]), int(argv[3]))
            if image is None:
                print("no frame decoded", file=sys.stderr)
                return 1

View on GitHub (pinned to 0b6a024f2f)

Solutions

  1. Verify the file with ffprobe: if ffprobe shows no video stream or a codec your OpenCV build lacks, transcode first (ffmpeg -i in.mp4 -c:v libx264 -pix_fmt yuv420p out.mp4).
  2. Ensure the OpenCV build has FFmpeg support: check cv2.getBuildInformation() for 'FFMPEG: YES'; reinstall opencv-python (not headless) if missing.
  3. Validate the upload before decoding: reject zero-byte files and files with no video stream (e.g. probe with video_thumbnails.probe_video first).
  4. If the file is simply corrupt from a failed upload, ask the user to re-upload.

Example fix

// before
frames = list(iter_video_frames(path))  # ValueError: No frames decoded from path
// after
info = probe_video(path, timeout=30)
if info is None or info.width == 0:
    raise HTTPException(415, f"Unsupported or corrupt video: {path}")
frames = list(iter_video_frames(path))
Defensive patterns

Strategy: validation

Validate before calling

import os
def decodable_video_ready(path: str) -> bool:
    return os.path.isfile(path) and os.path.getsize(path) > 0
# plus a pre-check:
# info = probe_video(path, timeout=30); info is not None

Try / catch

try:
    frames = list(iter_video_frames(path))
except ValueError as e:
    if "No frames decoded" in str(e):
        handle_unsupported_video(path)  # reject upload / transcode

Prevention

When it happens

Trigger: Calling _stream/main on a video whose codec OpenCV's FFmpeg backend cannot decode (e.g. exotic codecs like ProRes, AV1 without support), a truncated/corrupt file, an audio-only file, or a path pointing to an empty file. Also occurs if cv2.cvtColor receives frames but the capture immediately hits EOF due to a damaged container index.

Common situations: Users upload videos recorded with device-specific codecs not in the installed OpenCV's FFmpeg build; headless Docker images missing opencv-python full video support (opencv-python-headless without FFmpeg libs); zero-byte or interrupted uploads; testing with a text file renamed to .mp4.

Related errors

AI-assisted analysis of invoke-ai/InvokeAI@0b6a024f2f (2026-08-29). Data as JSON: /api/errors/148c77bfb90ce908. Report an issue: GitHub.