sgl-project/sglang · error · ValueError

Hunyuan3D SD2.1 UNet requires two ResNet layers and one tran

Error message

Hunyuan3D SD2.1 UNet requires two ResNet layers and one transformer layer per block.

What it means

Raised by StableDiffusionUNetConfig.validate() when layers_per_block != 2 or transformer_layers_per_block != 1. The native SD2 UNet implementation hard-codes the Hunyuan3D SD2.1 block structure of two ResNet layers and one transformer layer per block.

Source

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

            "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,
    *,
    flip_sin_to_cos: bool,
    downscale_freq_shift: float,

View on GitHub (pinned to 0132848349)

Solutions

1. Set layers_per_block = 2 in the config
2. Set transformer_layers_per_block = 1 in the config
3. Use the original Hunyuan3D SD2.1 checkpoint config

Example fix

// before
layers_per_block = 3
transformer_layers_per_block = 2
// after
layers_per_block = 2
transformer_layers_per_block = 1

assert cfg_dict.get("layers_per_block") == 2 and cfg_dict.get("transformer_layers_per_block", 1) == 1

def has_hunyuan_block_layout(d: dict) -> bool:
    return d.get("layers_per_block") == 2 and d.get("transformer_layers_per_block", 1) == 1

When it happens

Trigger: Loading a UNet config via from_dict where layers_per_block is anything other than 2, or transformer_layers_per_block is anything other than 1 (e.g. deeper UNets with 3 ResNet layers per block).

Common situations: Using a community fine-tuned SD2.1 variant with deeper blocks; porting a config from another diffusion framework that uses different layer counts.

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 four channel stages.
• 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/96642ef36a443072. Report an issue: GitHub.