hpcaitech/Open-Sora · error · ValueError

Unsupported time_compression_ratio: {time_compression_ratio}

Error message

Unsupported time_compression_ratio: {time_compression_ratio}.

What it means

The Encoder of the Hunyuan causal 3D VAE builds its downsampling schedule from time_compression_ratio and only supports specific values (the branches handle e.g. 4 and 8; the else covers everything else). Passing an unsupported ratio (e.g. 2, 6, 16) at AutoencoderKLCausal3D construction raises this ValueError immediately.

Source

Thrown at opensora/models/hunyuan_vae/vae.py:84

        # down
        output_channel = block_out_channels[0]
        for i, _ in enumerate(block_out_channels):
            input_channel = output_channel
            output_channel = block_out_channels[i]
            is_final_block = i == len(block_out_channels) - 1
            num_spatial_downsample_layers = int(np.log2(spatial_compression_ratio))
            num_time_downsample_layers = int(np.log2(time_compression_ratio))

            if time_compression_ratio == 4:
                add_spatial_downsample = bool(i < num_spatial_downsample_layers)
                add_time_downsample = bool(
                    i >= (len(block_out_channels) - 1 - num_time_downsample_layers) and not is_final_block
                )
            elif time_compression_ratio == 8:
                add_spatial_downsample = bool(i < num_spatial_downsample_layers)
                add_time_downsample = bool(i < num_spatial_downsample_layers)
            else:
                raise ValueError(f"Unsupported time_compression_ratio: {time_compression_ratio}.")

            downsample_stride_HW = (2, 2) if add_spatial_downsample else (1, 1)
            downsample_stride_T = (2,) if add_time_downsample else (1,)
            downsample_stride = tuple(downsample_stride_T + downsample_stride_HW)
            down_block = DownEncoderBlockCausal3D(
                num_layers=self.layers_per_block,
                in_channels=input_channel,
                out_channels=output_channel,
                dropout=dropout,
                add_downsample=bool(add_spatial_downsample or add_time_downsample),
                downsample_stride=downsample_stride,
                resnet_eps=1e-6,
                resnet_act_fn=act_fn,
                resnet_groups=norm_num_groups,
            )

            self.down_blocks.append(down_block)

View on GitHub (pinned to 7ad6a96a13)

Solutions

  1. Set time_compression_ratio to a supported value (4 or 8) in the encoder config
  2. If loading from a checkpoint, check the checkpoint's config for the original ratio and keep it
  3. Match the encoder ratio with the corresponding decoder config (vae.py:208 enforces the same set)

Example fix

# before
encoder = Encoder(..., time_compression_ratio=6)
# after
encoder = Encoder(..., time_compression_ratio=4)
Defensive patterns

Strategy: validation

Validate before calling

SUPPORTED_TCR = {4, 8}
assert time_compression_ratio in SUPPORTED_TCR, f"use one of {SUPPORTED_TCR}"

Type guard

def is_supported_tcr(v) -> bool:
    return v in {4, 8}

Try / catch

try:
    enc = Encoder(..., time_compression_ratio=tcr)
except ValueError:
    tcr = 4
    enc = Encoder(..., time_compression_ratio=tcr)

Prevention

When it happens

Trigger: Constructing the encoder with config time_compression_ratio not equal to one of the supported values (commonly 4 or 8), typically from a YAML/JSON model config or a checkpoint's config dict.

Common situations: Experimenting with temporal compression settings for video VAE; loading a config edited by hand; porting configs between opensora versions where supported ratios changed.

Related errors

AI-assisted analysis of hpcaitech/Open-Sora@7ad6a96a13 (2026-08-28). Data as JSON: /api/errors/107bba86f2d19ee6. Report an issue: GitHub.