Comfy-Org/ComfyUI · error · ValueError

MiniMaxH3AddGuide expects a MiniMax H3 AV latent

Error message

MiniMaxH3AddGuide expects a MiniMax H3 AV latent

What it means

MiniMaxH3AddGuide validates that the incoming latent is a MiniMax H3 audiovisual latent: a nested tensor bundle with exactly 2 tensors where the video tensor is 5D with 24 latent channels. Any latent not matching that exact structure raises this error before any encoding happens.

Source

Thrown at comfy_extras/nodes_minimax_h3.py:190

            inputs=[
                io.Conditioning.Input("positive"),
                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

View on GitHub (pinned to 1c6d8d45b3)

Solutions

1. Feed the node a latent produced by the MiniMax H3 nodes in the same file (e.g. the H3 empty/reference latent node) so the nested 2-tensor structure is guaranteed.
2. If the latent came from a checkpoint save, re-encode from the H3 pipeline instead of loading a foreign latent file.
3. Verify upstream latent shape in Python: check samples.is_nested, len(tensors)==2, and video tensor shape[1]==24.

samples = latent["samples"]
ok = (samples.is_nested and len(samples.tensors) == 2
      and samples.tensors[0].ndim == 5 and samples.tensors[0].shape[1] == 24)
if not ok:
    raise UserFacingError('latent is not a MiniMax H3 AV latent')

def is_minimax_h3_av_latent(latent) -> bool:
    s = latent["samples"]
    return (s.is_nested and len(s.tensors) == 2
            and s.tensors[0].ndim == 5 and s.tensors[0].shape[1] == 24)

When it happens

Trigger: Connecting a standard SD/SDXL/Flux image latent, a non-nested Wan latent, or a MiniMax video-only latent (single tensor) to the node's latent input; also latents produced by a generic EmptyLatentImage node.

Common situations: Wiring a workflow built for image models into the MiniMax H3 AV pipeline; reusing a cached or saved latent from another model family; forgetting that H3 couples video and audio in one nested latent.

Related errors

• SeedVR2 expected {name} to be 5-D native latent, got shape {
• SeedVR2 expected {name} channels to be {channels}, got shape
• Adding guide to a combined AV latent is not supported.
• Latent spatial size {latent_width}x{latent_height} must be d
• audio latent {} cannot be fitted to {}

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