invoke-ai/InvokeAI · error · ValueError

{field_name}={value} is out of range for a {n_frames}-frame

Error message

{field_name}={value} is out of range for a {n_frames}-frame video.

What it means

Static helper _resolve_index validates a single frame index. Negative values are interpreted as offsets from the end (value + n_frames); if the resolved index is still negative or >= n_frames, the index does not point at a real frame and ValueError is raised.

Source

Thrown at invokeai/app/invocations/video_frame_extract_range.py:243

                width=base.width,
                height=base.height,
                num_frames=base.num_frames,
                fps=base.fps,
                duration=base.duration,
                start_frame=start,
                end_frame=end,
            )
        finally:
            try:
                tmp_path.unlink(missing_ok=True)
            except Exception:
                pass

    @staticmethod
    def _resolve_index(value: int, n_frames: int, field_name: str) -> int:
        resolved = value + n_frames if value < 0 else value
        if resolved < 0 or resolved >= n_frames:
            raise ValueError(f"{field_name}={value} is out of range for a {n_frames}-frame video.")
        return resolved

View on GitHub (pinned to 0b6a024f2f)

Solutions

Probe the video's frame count first and clamp indices to [0, n_frames-1]
For 'until the end', use end_frame=-1 instead of n_frames
Fix negative indices that underflow (magnitude must be <= n_frames)
Correct board/workflow values that were captured from another video

Example fix

// before
invocation.end_frame = n_frames  # off by one, out of range
// after
invocation.end_frame = n_frames - 1  # or -1 for the last frame

Defensive patterns

Strategy: validation

Validate before calling

n_frames = probe_frame_count(video)
def clamp(v): return v + n_frames if v < 0 else v
start_frame = max(0, min(clamp(start_frame), n_frames - 1))
end_frame = max(0, min(clamp(end_frame), n_frames - 1))

Type guard

def index_in_range(value: int, n_frames: int) -> bool:
    r = value + n_frames if value < 0 else value
    return 0 <= r < n_frames

Try / catch

try:
    clip = invocation.invoke(context)
except ValueError as e:
    if "is out of range for a" in str(e):
        n = int(str(e).rsplit('-', 1)[-1].split('-frame')[0])
        invocation.start_frame = min(invocation.start_frame % n, n - 1)
        invocation.end_frame = min(invocation.end_frame % n, n - 1)
        clip = invocation.invoke(context)
    else:
        raise

Prevention

Clamp indices against a fresh frame-count probe before every run
Use -1 for the last frame rather than n_frames
Never reuse absolute ranges captured from a different video
Handle negative indices as end-relative, not clamping

When it happens

Trigger: start_frame or end_frame >= n_frames (e.g. start_frame=5000 on a 2400-frame video), or a negative value more negative than -n_frames (e.g. start_frame=-99999 resolving to a negative number).

Common situations: Copy-pasted range values from a different (longer) video, off-by-one where end_frame equals n_frames instead of n_frames - 1, misunderstanding negative indexing as clamping, ranges computed from a stale metadata probe.

Related errors

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