Comfy-Org/ComfyUI · error · ValueError

anchoring guide frames needs the vae input

Error message

anchoring guide frames needs the vae input

What it means

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.

Source

Thrown at comfy_extras/nodes_minimax_h3.py:201

            outputs=[io.Conditioning.Output(display_name="positive")],
        )

    @classmethod
    def execute(cls, positive, latent, frame_idx, vae=None, audio_vae=None, image=None, audio=None) -> io.NodeOutput:
        samples = latent["samples"]
        if not samples.is_nested or len(samples.tensors) != 2 or samples.tensors[0].ndim != 5 or samples.tensors[0].shape[1] != 24:
            raise ValueError("MiniMaxH3AddGuide expects a MiniMax H3 AV latent")
        if image is None and audio is None:
            raise ValueError("MiniMaxH3AddGuide needs an image or an audio to anchor")
        video = samples.tensors[0]
        height = video.shape[3] * 16
        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)

View on GitHub (pinned to 1c6d8d45b3)

Solutions

1. Connect the MiniMax H3 VAE (video VAE) to the vae input.
2. Check that vae and audio_vae are not crossed: vae encodes image frames, audio_vae encodes the soundtrack.
3. If you did not intend an image anchor, disconnect the image input to take the audio-only path.

if image is not None and vae is None:
    raise UserFacingError('connect the H3 VAE to anchor guide frames')

When it happens

Trigger: Connecting image while leaving vae unconnected; or connecting vae to audio_vae instead by mistake.

Common situations: 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.

Related errors

• MiniMaxH3AddGuide needs an image or an audio to anchor
• anchoring guide audio needs the audio_vae input
• This Controlnet needs a VAE but none was provided, please us
• Unknown normalization type: {norm_type}
• Unknown activation type: {activation_type}

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