invoke-ai/InvokeAI · error · ValueError

Failed to extract frame {index} from {self.video.video_name}

Error message

Failed to extract frame {index} from {self.video.video_name}.

What it means

Thrown when extract_video_frame returned None despite a valid index, i.e. the decoder could not actually produce the requested frame. This separates 'the index was valid' from 'decoding succeeded' failures.

Source

Thrown at invokeai/app/invocations/video_frame_extract.py:72

        if index < 0:
            n_frames = decoder_frame_count(video_path)
            if n_frames is None:
                _, _, duration, fps = probe_video(video_path)
                if not fps or duration <= 0:
                    raise ValueError(
                        f"Cannot resolve negative frame index for video {self.video.video_name}: "
                        f"probe returned duration={duration}, fps={fps}."
                    )
                n_frames = int(round(duration * fps))
            if n_frames <= 0:
                raise ValueError(f"Video {self.video.video_name} has no decodable frames (probed {n_frames}).")
            index = n_frames + index
            if index < 0:
                raise ValueError(f"frame_index {self.frame_index} is out of range for a {n_frames}-frame video.")

        frame = extract_video_frame(video_path, frame_index=index)
        if frame is None:
            raise ValueError(f"Failed to extract frame {index} from {self.video.video_name}.")

        image_dto = context.images.save(image=frame)
        return ImageOutput.build(image_dto=image_dto)

View on GitHub (pinned to 0b6a024f2f)

Solutions

Clamp index to decoder_frame_count(path) rather than the probe estimate
Re-encode the video with ffmpeg to repair decode errors
Retry with a nearby frame index
Use an exact frame count from decoding instead of duration*fps

Example fix

// before
index = int(round(duration * fps)) - 1  # estimate can exceed real frames
// after
n = decoder_frame_count(path)
index = min(index, (n or 1) - 1)

Defensive patterns

Strategy: retry

Validate before calling

n = decoder_frame_count(path)
if n is not None:
    index = min(index, n - 1)

Try / catch

try:
    out = extract.invoke(context)
except ValueError as e:
    if 'Failed to extract frame' in str(e):
        out = rebuild(frame_index=max(0, index - 1)).invoke(context)  # retry nearby frame
    else:
        raise

Prevention

Clamp index to decoder_frame_count, not duration*fps estimates
Re-encode sources with decode errors
Keep a fallback index (e.g. frame 0) for critical pipelines

When it happens

Trigger: invoke(): index passed validation, but extract_video_frame(video_path, frame_index=index) returns None (decoder error at seek/decode time, e.g. index beyond actual decodable frames despite metadata count).

Common situations: Metadata frame count (duration*fps estimate) exceeding real decodable frames; corrupted frames mid-file; VFR videos where duration*fps overestimates.

Related errors

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