sgl-project/sglang · error · ValueError

Hunyuan3D SD2.1 checkpoints require linear projection.

Error message

Hunyuan3D SD2.1 checkpoints require linear projection.

What it means

Raised by StableDiffusionUNetConfig.validate() when use_linear_projection is falsy. Hunyuan3D SD2.1 checkpoints were exported with linear projection enabled in the attention blocks, and the native reimplementation assumes that layout.

Source

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

            "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,
) -> torch.Tensor:
    half_dim = embedding_dim // 2
    exponent = -math.log(10000) * torch.arange(
        half_dim, dtype=torch.float32, device=timesteps.device
    )

View on GitHub (pinned to 0132848349)

Solutions

1. Set use_linear_projection = true in the UNet config
2. Use the Hunyuan3D SD2.1 checkpoint that was exported with linear projection

Example fix

// before
use_linear_projection = false
// after
use_linear_projection = true

if not cfg_dict.get("use_linear_projection", False):
    cfg_dict["use_linear_projection"] = True  # only if checkpoint actually uses it

def uses_linear_projection(d: dict) -> bool:
    return bool(d.get("use_linear_projection"))

When it happens

Trigger: Loading an SD2 UNet config with use_linear_projection = false or omitting it while running the Hunyuan3D native UNet path.

Common situations: Using a vanilla SD2.1 base checkpoint (which does not use linear projection) with the Hunyuan3D-native loader; hand-written config dicts missing the flag.

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 UNet requires two ResNet layers and one tran
• 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/fc5bf880faf29e64. Report an issue: GitHub.