{"record":{"id":"565fe5b6abc35bd0","repo":"Comfy-Org/ComfyUI","slug":"anchoring-guide-frames-needs-the-vae-input","errorCode":null,"errorMessage":"anchoring guide frames needs the vae input","messagePattern":"anchoring guide frames needs the vae input","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"comfy_extras/nodes_minimax_h3.py","lineNumber":201,"sourceCode":"            outputs=[io.Conditioning.Output(display_name=\"positive\")],\n        )\n\n    @classmethod\n    def execute(cls, positive, latent, frame_idx, vae=None, audio_vae=None, image=None, audio=None) -> io.NodeOutput:\n        samples = latent[\"samples\"]\n        if not samples.is_nested or len(samples.tensors) != 2 or samples.tensors[0].ndim != 5 or samples.tensors[0].shape[1] != 24:\n            raise ValueError(\"MiniMaxH3AddGuide expects a MiniMax H3 AV latent\")\n        if image is None and audio is None:\n            raise ValueError(\"MiniMaxH3AddGuide needs an image or an audio to anchor\")\n        video = samples.tensors[0]\n        height = video.shape[3] * 16\n        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)","sourceCodeStart":183,"sourceCodeEnd":219,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy_extras/nodes_minimax_h3.py#L183-L219","documentation":"When an image is supplied to MiniMaxH3AddGuide it must be VAE-encoded into latent space, which requires the vae input. The vae socket is optional only for the audio-only path, so image without vae is rejected before _resize/vae.encode would fail with a NoneType error.","triggerScenarios":"Connecting image while leaving vae unconnected; or connecting vae to audio_vae instead by mistake.","commonSituations":"Swapping the two optional VAE sockets (vae vs audio_vae) in a dense graph; copying an audio-only example workflow and adding an image without adding the VAE loader.","solutions":["Connect the MiniMax H3 VAE (video VAE) to the vae input.","Check that vae and audio_vae are not crossed: vae encodes image frames, audio_vae encodes the soundtrack.","If you did not intend an image anchor, disconnect the image input to take the audio-only path."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"if image is not None and vae is None:\n    raise UserFacingError('connect the H3 VAE to anchor guide frames')","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always connect the video VAE when an image anchor is used.","Keep vae and audio_vae sockets straight (video vs audio)."],"tags":["minimax-h3","vae","required-input","wiring"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}