Comfy-Org/ComfyUI · error · ValueError

MiniMaxH3AddGuide needs an image or an audio to anchor

Error message

MiniMaxH3AddGuide needs an image or an audio to anchor

What it means

MiniMaxH3AddGuide requires at least one anchor medium: an image (guide frame / first-frame clip) or an audio track. Both inputs are optional individually, but leaving both unconnected makes the node a no-op, so it fails fast instead of silently returning unchanged conditioning.

Source

Thrown at comfy_extras/nodes_minimax_h3.py:192

                io.Vae.Input("vae", optional=True, tooltip="Video VAE, needed when an image is connected."),
                io.Vae.Input("audio_vae", optional=True, tooltip="Audio VAE, needed when an audio is connected."),
                io.Latent.Input("latent"),
                io.Image.Input("image", optional=True, tooltip="Image or video frames to anchor. Multi-frame batches are anchored as a clip and cropped down to the model's valid clip lengths: 5, 22, 39... (17k + 5) frames. Batches shorter than 5 frames use only the first image."),
                io.Audio.Input("audio", optional=True,
                               tooltip="Soundtrack to anchor starting at the same frame index, cropped to the video's remaining duration."),
                io.Int.Input("frame_idx", default=0, min=-9999, max=9999,
                             tooltip="Frame index to anchor the image or the clip's first frame at. Negative values are counted from the end of the video."),
            ],
            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:

View on GitHub (pinned to 1c6d8d45b3)

Solutions

1. Connect an image batch or an audio clip to the corresponding input.
2. If you only want to pass conditioning through unchanged, remove the node from the chain.
3. If a conditional branch may supply neither, gate the node with a bypass/switch so it never executes.

if image is None and audio is None:
    raise UserFacingError('connect an image or an audio to MiniMaxH3AddGuide')

When it happens

Trigger: Calling execute with image=None and audio=None, typically by leaving both optional sockets unconnected in the graph.

Common situations: Building the graph incrementally and previewing before wiring the guide; misreading 'optional' as 'not required at all'; a switch/mux node that returns None on the inactive branch.

Related errors

• anchoring guide frames needs the vae input
• anchoring guide audio needs the audio_vae input
• Dall-E 2 image editing requires an image AND a mask
• MiniMaxH3AddGuide expects a MiniMax H3 AV latent
• frame_idx {} is outside the video's {} frames

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