invoke-ai/InvokeAI · error · ValueError

Cannot resolve negative frame index for video {self.video.vi

Error message

Cannot resolve negative frame index for video {self.video.video_name}: probe returned duration={duration}, fps={fps}.

What it means

Thrown in VideoFrameExtract.invoke when frame_index is negative and the frame count cannot be resolved. It first tries decoder_frame_count; if that returns None it falls back to probing duration*fps, and raises when fps is 0/None or duration <= 0. Negative indexing is impossible without a reliable frame count.

Source

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

        description="Index of the frame to extract. 0 = first frame, -1 = last frame, -2 = second-to-last, etc.",
        ui_component=UIComponent.VideoFrameIndex,
    )

    def invoke(self, context: InvocationContext) -> ImageOutput:
        video_path = context.videos.get_path(self.video.video_name)

        # Resolve negative indices against the actual frame count rather than
        # trusting imageio plugins to accept index=-1 uniformly. Use the decoder's
        # 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 non-negative frame_index
  2. Re-encode the video to a standard MP4/H.264 file so probe can read duration and fps
  3. Verify the source file is complete and not a stream/pipe
  4. Check the video plays and reports duration via ffprobe

Example fix

// before
VideoFrameExtract(video=v, frame_index=-1)  # probe returns fps=0
// after
VideoFrameExtract(video=v, frame_index=0)  # or fix source encoding
Defensive patterns

Strategy: validation

Validate before calling

probe = probe_video(path)
if frame_index < 0 and (not probe.fps or probe.duration <= 0) and decoder_frame_count(path) is None:
    raise ValueError('cannot resolve negative frame index: probe invalid')

Try / catch

try:
    out = extract.invoke(context)
except ValueError as e:
    if 'Cannot resolve negative frame index' in str(e):
        out = rebuild(frame_index=0).invoke(context)
    else:
        raise

Prevention

When it happens

Trigger: invoke() with frame_index < 0 where decoder_frame_count(path) returns None and probe_video(path) yields invalid fps or duration (fps falsy or duration <= 0).

Common situations: Corrupt or unusual containers that ffmpeg probe cannot measure; live streams or pipes with unknown duration; codec metadata missing fps.

Related errors

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