{"record":{"id":"5c9426d04dd0df75","repo":"Comfy-Org/ComfyUI","slug":"minimaxh3addguide-expects-a-minimax-h3-av-latent","errorCode":null,"errorMessage":"MiniMaxH3AddGuide expects a MiniMax H3 AV latent","messagePattern":"MiniMaxH3AddGuide expects a MiniMax H3 AV latent","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"comfy_extras/nodes_minimax_h3.py","lineNumber":190,"sourceCode":"            inputs=[\n                io.Conditioning.Input(\"positive\"),\n                io.Vae.Input(\"vae\", optional=True, tooltip=\"Video VAE, needed when an image is connected.\"),\n                io.Vae.Input(\"audio_vae\", optional=True, tooltip=\"Audio VAE, needed when an audio is connected.\"),\n                io.Latent.Input(\"latent\"),\n                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.\"),\n                io.Audio.Input(\"audio\", optional=True,\n                               tooltip=\"Soundtrack to anchor starting at the same frame index, cropped to the video's remaining duration.\"),\n                io.Int.Input(\"frame_idx\", default=0, min=-9999, max=9999,\n                             tooltip=\"Frame index to anchor the image or the clip's first frame at. Negative values are counted from the end of the video.\"),\n            ],\n            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","sourceCodeStart":172,"sourceCodeEnd":208,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy_extras/nodes_minimax_h3.py#L172-L208","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","If the latent came from a checkpoint save, re-encode from the H3 pipeline instead of loading a foreign latent file.","Verify upstream latent shape in Python: check samples.is_nested, len(tensors)==2, and video tensor shape[1]==24."],"exampleFix":null,"handlingStrategy":"type-guard","validationCode":"samples = latent[\"samples\"]\nok = (samples.is_nested and len(samples.tensors) == 2\n      and samples.tensors[0].ndim == 5 and samples.tensors[0].shape[1] == 24)\nif not ok:\n    raise UserFacingError('latent is not a MiniMax H3 AV latent')","typeGuard":"def is_minimax_h3_av_latent(latent) -> bool:\n    s = latent[\"samples\"]\n    return (s.is_nested and len(s.tensors) == 2\n            and s.tensors[0].ndim == 5 and s.tensors[0].shape[1] == 24)","tryCatchPattern":null,"preventionTips":["Only use latents produced by the MiniMax H3 nodes in the same package.","Never feed generic EmptyLatent or other-model latents into H3 AV nodes.","Tag saved latents with the model family to avoid mixing."],"tags":["minimax-h3","latent","validation","audiovisual"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}