Comfy-Org/ComfyUI · error · ValueError

anchoring guide audio needs the audio_vae input

Error message

anchoring guide audio needs the audio_vae input

What it means

When audio is supplied to MiniMaxH3AddGuide it must be encoded with the audio VAE, so the audio_vae input is mandatory on that path. It is optional only for image-only usage; audio without audio_vae fails fast before _encode_ref_audio would crash on None.

Source

Thrown at comfy_extras/nodes_minimax_h3.py:223

            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)

        if audio is not None:
            if audio_vae is None:
                raise ValueError("anchoring guide audio needs the audio_vae input")
            audio_latent, audio_rt = _encode_ref_audio(audio_vae, audio)
            # the streams share one time axis: FRAME_RESCALE per pixel frame, 1.0 per audio latent frame
            max_rt = math.floor(samples.tensors[1].shape[-1] - FRAME_RESCALE * resolved_frame_index)
            if max_rt < 1:
                raise ValueError("frame_idx {} is past the end of the video's audio track".format(frame_idx))
            if audio_rt > max_rt:
                audio_latent = audio_latent[..., :max_rt].clone()
            keyframe["audio_latent"] = audio_latent

        keyframes = list(positive[0][1].get("minimax_keyframes", []))
        keyframes.append(keyframe)
        positive = node_helpers.conditioning_set_values(positive, {"minimax_keyframes": keyframes})
        return io.NodeOutput(positive)


class MiniMaxH3ReferenceToVideo(io.ComfyNode):
    """ref2va: prompt + reference images / videos / audio -> conditioning + AV latent.

View on GitHub (pinned to 1c6d8d45b3)

Solutions

1. Connect the MiniMax H3 audio VAE to the audio_vae input.
2. Verify socket order: vae for image frames, audio_vae for the soundtrack.
3. If audio was connected unintentionally, disconnect it to use the image-only path.

if audio is not None and audio_vae is None:
    raise UserFacingError('connect the H3 audio VAE to anchor guide audio')

When it happens

Trigger: Connecting audio while audio_vae is unconnected; or plugging the video VAE into the wrong socket and leaving audio_vae empty.

Common situations: Porting an image-only H3 workflow and adding a soundtrack without the audio VAE loader; swapping vae/audio_vae connections in a crowded graph.

Related errors

• MiniMaxH3AddGuide needs an image or an audio to anchor
• anchoring guide frames needs the vae input
• Input audio must have {expected_channels} channels, got {wav
• Unsupported audio_channels: {audio_channels}
• Vocoder is missing upsample_factor; cannot infer output samp

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