{"record":{"id":"32a9d8aebf86838e","repo":"invoke-ai/InvokeAI","slug":"field-name-value-is-out-of-range-for-a-n-fram","errorCode":null,"errorMessage":"{field_name}={value} is out of range for a {n_frames}-frame video.","messagePattern":"(.+?)=(.+?) is out of range for a (.+?)-frame video\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"invokeai/app/invocations/video_frame_extract_range.py","lineNumber":243,"sourceCode":"                width=base.width,\n                height=base.height,\n                num_frames=base.num_frames,\n                fps=base.fps,\n                duration=base.duration,\n                start_frame=start,\n                end_frame=end,\n            )\n        finally:\n            try:\n                tmp_path.unlink(missing_ok=True)\n            except Exception:\n                pass\n\n    @staticmethod\n    def _resolve_index(value: int, n_frames: int, field_name: str) -> int:\n        resolved = value + n_frames if value < 0 else value\n        if resolved < 0 or resolved >= n_frames:\n            raise ValueError(f\"{field_name}={value} is out of range for a {n_frames}-frame video.\")\n        return resolved\n","sourceCodeStart":225,"sourceCodeEnd":245,"githubUrl":"https://github.com/invoke-ai/InvokeAI/blob/0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06/invokeai/app/invocations/video_frame_extract_range.py#L225-L245","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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"],"exampleFix":"// before\ninvocation.end_frame = n_frames  # off by one, out of range\n// after\ninvocation.end_frame = n_frames - 1  # or -1 for the last frame","handlingStrategy":"validation","validationCode":"n_frames = probe_frame_count(video)\ndef clamp(v): return v + n_frames if v < 0 else v\nstart_frame = max(0, min(clamp(start_frame), n_frames - 1))\nend_frame = max(0, min(clamp(end_frame), n_frames - 1))","typeGuard":"def index_in_range(value: int, n_frames: int) -> bool:\n    r = value + n_frames if value < 0 else value\n    return 0 <= r < n_frames","tryCatchPattern":"try:\n    clip = invocation.invoke(context)\nexcept ValueError as e:\n    if \"is out of range for a\" in str(e):\n        n = int(str(e).rsplit('-', 1)[-1].split('-frame')[0])\n        invocation.start_frame = min(invocation.start_frame % n, n - 1)\n        invocation.end_frame = min(invocation.end_frame % n, n - 1)\n        clip = invocation.invoke(context)\n    else:\n        raise","preventionTips":["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"],"tags":["validation","video","index-out-of-range"],"backgroundTag":"index-out-of-range","analyzedSha":"0b6a024f2ff6a86bfb953dcdb9cc504ef7397a06","analyzedAt":"2026-08-29T04:46:49.967Z","schemaVersion":2},"datasetVersion":"2026-08-29T07:17:48.351Z"}