{"record":{"id":"0a42308a92091582","repo":"Comfy-Org/ComfyUI","slug":"a-frame-guide-clip-at-frame-idx-does-not-fit","errorCode":null,"errorMessage":"a {} frame guide clip at frame_idx {} does not fit in the video's {} frames","messagePattern":"a (.+?) frame guide clip at frame_idx (.+?) does not fit in the video's (.+?) frames","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"comfy_extras/nodes_minimax_h3.py","lineNumber":213,"sourceCode":"        width = video.shape[4] * 16\n        frame_count = sum(FRAME_PER_TOKEN[k % 5] for k in range(video.shape[2]))\n\n        guide_frames = 1\n        if image is not None:\n            if vae is None:\n                raise ValueError(\"anchoring guide frames needs the vae input\")\n            guide_frames = image.shape[0]\n            if guide_frames < 5:\n                guide_frames = 1\n            else:\n                while guide_frames % 17 != 5:\n                    guide_frames -= 1\n\n        resolved_frame_index = frame_idx if frame_idx >= 0 else frame_count + frame_idx\n        if resolved_frame_index < 0 or resolved_frame_index + guide_frames > frame_count:\n            if guide_frames == 1:\n                raise ValueError(\"frame_idx {} is outside the video's {} frames\".format(frame_idx, frame_count))\n            raise ValueError(\"a {} frame guide clip at frame_idx {} does not fit in the video's {} frames\".format(\n                guide_frames, frame_idx, frame_count))\n\n        keyframe = {\"resolved_frame_index\": resolved_frame_index}\n        if image is not None:\n            frames = _resize(image[:guide_frames], width, height, \"center\")\n            keyframe[\"latent\"] = vae.encode(frames)\n\n        if audio is not None:\n            if audio_vae is None:\n                raise ValueError(\"anchoring guide audio needs the audio_vae input\")\n            audio_latent, audio_rt = _encode_ref_audio(audio_vae, audio)\n            # the streams share one time axis: FRAME_RESCALE per pixel frame, 1.0 per audio latent frame\n            max_rt = math.floor(samples.tensors[1].shape[-1] - FRAME_RESCALE * resolved_frame_index)\n            if max_rt < 1:\n                raise ValueError(\"frame_idx {} is past the end of the video's audio track\".format(frame_idx))\n            if audio_rt > max_rt:\n                audio_latent = audio_latent[..., :max_rt].clone()\n            keyframe[\"audio_latent\"] = audio_latent","sourceCodeStart":195,"sourceCodeEnd":231,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy_extras/nodes_minimax_h3.py#L195-L231","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Lower frame_idx so the whole clip fits (frame_idx <= frame_count - guide_frames).","Shorten the image batch; note lengths are effectively rounded down to values congruent to 5 mod 17 (5, 22, 39, ...).","Extend the target latent's length so the guide clip fits at the desired position."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"n = image.shape[0]\nguide = 1 if n < 5 else next(m for m in range(n, 4, -1) if m % 17 == 5)\nresolved = frame_idx if frame_idx >= 0 else frame_count + frame_idx\nassert resolved + guide <= frame_count, 'guide clip does not fit'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Remember clip lengths are trimmed to n % 17 == 5 (5, 22, 39, ...).","Choose frame_idx <= frame_count - guide_frames.","Shorten the guide batch or extend the target latent."],"tags":["minimax-h3","frame-index","bounds","guide-clip"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}