Comfy-Org/ComfyUI · error · ValueError

Adding guide to a combined AV latent is not supported.

Error message

Adding guide to a combined AV latent is not supported.

What it means

Raised by LTXGuide.append_keyframe() when either the incoming latent or the guiding latent has a channel dimension different from the expected in_channels (default 128). LTX video latents have 128 channels; a tensor with more channels is a combined audio+video latent (VAE outputs audio channels concatenated), and per-frame guide injection into such a combined latent is not supported.

Source

Thrown at comfy_extras/nodes_lt.py:380

        # so that RoPE represents the correct middle point of each token.
        # keyframe_idxs dims: (batch, spatial_dim [t,h,w], token_id, [start, end])
        # We only adjust h,w (not t) in dim 1, and only end (not start) in dim 3.
        spatial_end_offset = (latent_downscale_factor - 1) * torch.tensor(
            scale_factors[1:],
            device=pixel_coords.device,
        ).view(1, -1, 1, 1)
        pixel_coords[:, 1:, :, 1:] += spatial_end_offset.to(pixel_coords.dtype)

        if keyframe_idxs is None:
            keyframe_idxs = pixel_coords
        else:
            keyframe_idxs = torch.cat([keyframe_idxs, pixel_coords], dim=2)
        return node_helpers.conditioning_set_values(cond, {"keyframe_idxs": keyframe_idxs})

    @classmethod
    def append_keyframe(cls, positive, negative, frame_idx, latent_image, noise_mask, guiding_latent, strength, scale_factors, guide_mask=None, in_channels=128, latent_downscale_factor=1, causal_fix=None):
        if latent_image.shape[1] != in_channels or guiding_latent.shape[1] != in_channels:
            raise ValueError("Adding guide to a combined AV latent is not supported.")

        positive = cls.add_keyframe_index(positive, frame_idx, guiding_latent, scale_factors, latent_downscale_factor, causal_fix=causal_fix)
        negative = cls.add_keyframe_index(negative, frame_idx, guiding_latent, scale_factors, latent_downscale_factor, causal_fix=causal_fix)

        if guide_mask is not None:
            target_h = max(noise_mask.shape[3], guide_mask.shape[3])
            target_w = max(noise_mask.shape[4], guide_mask.shape[4])

            if noise_mask.shape[3] == 1 or noise_mask.shape[4] == 1:
                noise_mask = noise_mask.expand(-1, -1, -1, target_h, target_w)

            if guide_mask.shape[3] == 1 or guide_mask.shape[4] == 1:
                guide_mask = guide_mask.expand(-1, -1, -1, target_h, target_w)
            mask = guide_mask - strength
        else:
            mask = torch.full(
                (noise_mask.shape[0], 1, guiding_latent.shape[2], noise_mask.shape[3], noise_mask.shape[4]),
                max(0.0, 1.0 - strength), # clamp here to amplify only via the attention mask

View on GitHub (pinned to 1c6d8d45b3)

Solutions

  1. Use a video-only latent (128 channels) for the guided path — drop the audio channels or encode video without audio.
  2. Make sure in_channels on the node matches the actual VAE latent channels of both latent_image and guiding_latent.
  3. Encode the guide frames with the same VAE as the base latent so channel counts agree.

Example fix

# before
latent = av_vae.encode(video_with_audio)  # channels == 128 + audio_ch -> raises

# after
latent = video_vae.encode(video)           # channels == 128
Defensive patterns

Strategy: validation

Validate before calling

IN_CHANNELS = 128
assert latent_image.shape[1] == IN_CHANNELS and guiding_latent.shape[1] == IN_CHANNELS, (
    f"combined AV latent detected ({latent_image.shape[1]} ch); supply a video-only {IN_CHANNELS}-ch latent")

Type guard

def is_video_only_latent(latent, in_channels: int = 128) -> bool:
    return latent["samples"].shape[1] == in_channels

Try / catch

try:
    out = LTXGuide.append_keyframe(positive, negative, frame_idx, latent, ...)
except ValueError as e:
    if "combined AV latent" in str(e):
        raise ValueError("Re-encode without audio so the latent has 128 video channels") from e
    raise

Prevention

When it happens

Trigger: Feeding the latent from an LTX VAE encode that includes audio (combined AV VAE output, channels > 128) into the append-keyframe guide node; mismatched in_channels parameter (passing 192 while the workflow uses 128-channel latents); using a guide latent encoded with a different VAE channel count than the base latent.

Common situations: LTX audio+video workflows where the VAE encode keeps the audio channels; mixing models with different latent channel counts (LTX-2 vs older checkpoints).

Related errors

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