Comfy-Org/ComfyUI · error · ValueError

a {} frame guide clip at frame_idx {} does not fit in the vi

Error message

a {} frame guide clip at frame_idx {} does not fit in the video's {} frames

What it means

For multi-frame guide clips (image batch >= 5), the clip length is first reduced to the H3-friendly form n % 17 == 5, then the check requires resolved_frame_index + guide_frames <= frame_count. If the trimmed clip does not fit ending before the last frame, this error reports the clip length, the requested index, and the total frames.

Source

Thrown at comfy_extras/nodes_minimax_h3.py:213

        width = video.shape[4] * 16
        frame_count = sum(FRAME_PER_TOKEN[k % 5] for k in range(video.shape[2]))

        guide_frames = 1
        if image is not None:
            if vae is None:
                raise ValueError("anchoring guide frames needs the vae input")
            guide_frames = image.shape[0]
            if guide_frames < 5:
                guide_frames = 1
            else:
                while guide_frames % 17 != 5:
                    guide_frames -= 1

        resolved_frame_index = frame_idx if frame_idx >= 0 else frame_count + frame_idx
        if resolved_frame_index < 0 or resolved_frame_index + guide_frames > frame_count:
            if guide_frames == 1:
                raise ValueError("frame_idx {} is outside the video's {} frames".format(frame_idx, frame_count))
            raise ValueError("a {} frame guide clip at frame_idx {} does not fit in the video's {} frames".format(
                guide_frames, frame_idx, frame_count))

        keyframe = {"resolved_frame_index": resolved_frame_index}
        if image is not None:
            frames = _resize(image[:guide_frames], width, height, "center")
            keyframe["latent"] = vae.encode(frames)

        if audio is not None:
            if audio_vae is None:
                raise ValueError("anchoring guide audio needs the audio_vae input")
            audio_latent, audio_rt = _encode_ref_audio(audio_vae, audio)
            # the streams share one time axis: FRAME_RESCALE per pixel frame, 1.0 per audio latent frame
            max_rt = math.floor(samples.tensors[1].shape[-1] - FRAME_RESCALE * resolved_frame_index)
            if max_rt < 1:
                raise ValueError("frame_idx {} is past the end of the video's audio track".format(frame_idx))
            if audio_rt > max_rt:
                audio_latent = audio_latent[..., :max_rt].clone()
            keyframe["audio_latent"] = audio_latent

View on GitHub (pinned to 1c6d8d45b3)

Solutions

1. Lower frame_idx so the whole clip fits (frame_idx <= frame_count - guide_frames).
2. Shorten the image batch; note lengths are effectively rounded down to values congruent to 5 mod 17 (5, 22, 39, ...).
3. Extend the target latent's length so the guide clip fits at the desired position.

n = image.shape[0]
guide = 1 if n < 5 else next(m for m in range(n, 4, -1) if m % 17 == 5)
resolved = frame_idx if frame_idx >= 0 else frame_count + frame_idx
assert resolved + guide <= frame_count, 'guide clip does not fit'

When it happens

Trigger: Anchoring e.g. a 22-frame clip (trimmed toward n%17==5, so 22 stays 22) at frame_idx near the end; any case where frame_idx + guide_frames > frame_count after trimming.

Common situations: First-frame anchoring of a long clip into a short video; not accounting for the n%17==5 trimming when eyeballing fit; using negative frame_idx with a multi-frame clip.

Related errors

• frame_idx {} is outside the video's {} frames
• frame_idx {} is past the end of the video's audio track
• MiniMaxH3AddGuide expects a MiniMax H3 AV latent
• MiniMaxH3AddGuide needs an image or an audio to anchor
• anchoring guide frames needs the vae input

AI-assisted analysis of Comfy-Org/ComfyUI@1c6d8d45b3 (2026-08-14). Data as JSON: /api/errors/0a42308a92091582. Report an issue: GitHub.