sgl-project/sglang · error · ValueError

Hunyuan3D SD2.1 UNet requires four channel stages.

Error message

Hunyuan3D SD2.1 UNet requires four channel stages.

What it means

Raised by StableDiffusionUNetConfig.validate() during from_dict when the UNet config's block_out_channels or attention_head_dim lists do not each have exactly 4 entries. The native SD2.1 UNet implementation only supports the Hunyuan3D four-level channel-stage layout, so any config deviating from 4 stages is rejected.

Source

Thrown at python/sglang/multimodal_gen/runtime/models/dits/stable_diffusion.py:93

        expected_down = (
            "CrossAttnDownBlock2D",
            "CrossAttnDownBlock2D",
            "CrossAttnDownBlock2D",
            "DownBlock2D",
        )
        expected_up = (
            "UpBlock2D",
            "CrossAttnUpBlock2D",
            "CrossAttnUpBlock2D",
            "CrossAttnUpBlock2D",
        )
        if self.down_block_types != expected_down or self.up_block_types != expected_up:
            raise ValueError(
                "The native SD2 UNet currently supports only the Hunyuan3D "
                "four-level SD2.1 block layout."
            )
        if len(self.block_out_channels) != 4 or len(self.attention_head_dim) != 4:
            raise ValueError("Hunyuan3D SD2.1 UNet requires four channel stages.")
        if self.layers_per_block != 2 or self.transformer_layers_per_block != 1:
            raise ValueError(
                "Hunyuan3D SD2.1 UNet requires two ResNet layers and one "
                "transformer layer per block."
            )
        if not self.use_linear_projection:
            raise ValueError("Hunyuan3D SD2.1 checkpoints require linear projection.")


@dataclass
class StableDiffusionUNetOutput:
    sample: torch.Tensor


def timestep_embedding(
    timesteps: torch.Tensor,
    embedding_dim: int,
    *,

View on GitHub (pinned to 0132848349)

Solutions

1. Set block_out_channels to exactly 4 values (e.g. [320, 640, 1280, 1280])
2. Set attention_head_dim to exactly 4 values matching the stages (e.g. [5, 10, 20, 20])
3. Use a checkpoint matching the Hunyuan3D SD2.1 architecture instead of an arbitrary SD2 UNet

Example fix

// before
block_out_channels = [320, 640, 1280]
attention_head_dim = [5, 10, 20]
// after
block_out_channels = [320, 640, 1280, 1280]
attention_head_dim = [5, 10, 20, 20]

cfg_dict = {...}
assert len(cfg_dict["block_out_channels"]) == 4 and len(cfg_dict["attention_head_dim"]) == 4, "need 4 channel stages"

def is_valid_sd2_unet_config(d: dict) -> bool:
    return len(d.get("block_out_channels", [])) == 4 and len(d.get("attention_head_dim", [])) == 4

When it happens

Trigger: Loading a StableDiffusion 2.1 UNet config (from_dict) where len(block_out_channels) != 4 or len(attention_head_dim) != 4 — e.g. a 3-stage or 5-stage custom UNet config dict.

Common situations: Pointing the loader at a non-Hunyuan3D SD2 checkpoint or a modified UNet with extra/removed channel stages; hand-editing the config JSON and dropping a channel entry.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

• The native SD2 UNet currently supports only the Hunyuan3D fo
• Hunyuan3D SD2.1 UNet requires two ResNet layers and one tran
• Hunyuan3D SD2.1 checkpoints require linear projection.
• The Hunyuan3D SD2.1 UNet has no added conditioning.
• bad compress_ratio {compress_ratio}

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/3aa06103ad94657a. Report an issue: GitHub.