invoke-ai/InvokeAI · error · ValueError

frame_index {self.frame_index} is out of range for a {n_fram

Error message

frame_index {self.frame_index} is out of range for a {n_frames}-frame video.

What it means

Thrown after resolving the total frame count when the requested negative frame_index still falls before frame 0 after offsetting (index = n_frames + index < 0). E.g. index -50 on a 20-frame video is out of range. This protects against silent wrap-around or clamping.

Source

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

        # frame count when available — duration*fps can be off-by-one for VFR
        # uploads or containers with approximate metadata, causing frame_index=-1
        # to point past the final frame.
        index = self.frame_index
        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

1. Use a smaller-magnitude negative index
2. Clamp or validate frame_index against the actual frame count before calling
3. Use a non-negative index if the clip length is known

Example fix

// before
VideoFrameExtract(video=v, frame_index=-50)  # video only has 20 frames
// after
n = decoder_frame_count(path) or 20
VideoFrameExtract(video=v, frame_index=-min(50, n))

n = decoder_frame_count(path) or int(round(duration*fps))
if frame_index < 0 and abs(frame_index) > n:
    frame_index = -n  # clamp to first frame

def in_range(frame_index: int, n_frames: int) -> bool:
    return -n_frames <= frame_index < n_frames

try:
    out = extract.invoke(context)
except ValueError as e:
    if 'out of range' in str(e):
        out = rebuild(frame_index=-n_frames).invoke(context)
    else:
        raise

When it happens

Trigger: invoke() with frame_index = -k where k > n_frames, so n_frames + frame_index < 0.

Common situations: Assuming the video is longer than it is; off-by-one in automated batch extraction scripts; using the same negative index across clips of different lengths.

Related errors

• {field_name}={value} is out of range for a {n_frames}-frame
• video_concat requires at least two input videos.
• All inputs must share the same dimensions. Got: {sorted(widt
• The requested transition needs an estimated {estimated_mib:.
• Clip {i} has {n_frames} frames but the requested transitions

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