sgl-project/sglang · error · ValueError

decoder_model_output_type must be 'x0' or 'v', got {arch.dec

Error message

decoder_model_output_type must be 'x0' or 'v', got {arch.decoder_model_output_type!r}.

What it means

The decoder is constructed to predict either x0 (denoised prediction) or v (velocity) parameterization, and the rest of the sampler must know which. __init__ validates arch.decoder_model_output_type against the allowed set ('x0','v') and raises for anything else.

Source

Thrown at python/sglang/multimodal_gen/runtime/models/decoders/ltx_2_5_diffusion_decoder.py:653

            hidden_states = hidden_states[:, 1:]
        return hidden_states


class LTX2VideoDiffusionDecoder3d(nn.Module):
    """Stages 1-4 upsample the latent into a context volume; stage 5 denoises
    patchified pixels conditioned on it."""

    def __init__(self, config: LTX25DiffusionDecoderConfig) -> None:
        super().__init__()
        arch = config.arch_config
        stage_channels = tuple(arch.decoder_stage_channels)
        stage_depths = tuple(arch.decoder_stage_depths)
        stage_kernels = tuple(tuple(k) for k in arch.decoder_stage_kernels)
        upsample_strides = tuple(tuple(s) for s in arch.decoder_upsample_strides)
        reductions = tuple(arch.decoder_upsample_channel_reductions)

        if arch.decoder_model_output_type not in ("x0", "v"):
            raise ValueError(
                "decoder_model_output_type must be 'x0' or 'v', got "
                f"{arch.decoder_model_output_type!r}."
            )
        # An inconsistent pair would only fail deep inside the first block.
        for stage_idx, reduction in enumerate(reductions):
            expected = stage_channels[stage_idx] // reduction
            if stage_channels[stage_idx + 1] != expected:
                raise ValueError(
                    f"decoder_stage_channels[{stage_idx + 1}] must be "
                    f"{expected}, got {stage_channels[stage_idx + 1]}."
                )

        self.patch_size = arch.patch_size
        self.out_channels = arch.out_channels
        self.timestep_scale_multiplier = arch.decoder_timestep_scale_multiplier
        self.model_output_type = arch.decoder_model_output_type
        self.default_num_inference_steps = arch.decoder_num_inference_steps
        self.temporal_compression_ratio = arch.temporal_compression_ratio

View on GitHub (pinned to 0132848349)

Solutions

1. Set decoder_model_output_type to exactly 'x0' or 'v' in the model arch config
2. If porting a checkpoint, determine which parameterization its training used (velocity → 'v', denoised → 'x0') and set accordingly
3. Add Literal['x0','v'] typing / config validation upstream so bad values fail at parse time

Example fix

# before
arch.decoder_model_output_type = "velocity"
# after
arch.decoder_model_output_type = "v"

if arch.decoder_model_output_type not in ("x0", "v"):
    raise ValueError("decoder_model_output_type must be 'x0' or 'v'")

from typing import Literal
OutputType = Literal["x0", "v"]
def is_output_type(t: str) -> bool:
    return t in ("x0", "v")

try:
    decoder = Ltx25DiffusionDecoder(arch)
except ValueError as e:
    if "decoder_model_output_type" in str(e):
        arch.decoder_model_output_type = "v"  # or 'x0' per checkpoint convention
        decoder = Ltx25DiffusionDecoder(arch)
    else:
        raise

When it happens

Trigger: Building the decoder from an arch/config object where decoder_model_output_type is misspelled, None, 'V', 'velocity', or from a config written for a different sampler convention.

Common situations: Hand-editing model configs; converting a checkpoint whose config uses a different naming for velocity prediction; case-sensitive string comparisons after dataclass defaults changed.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• decoder_stage_channels[{stage_idx + 1}] must be {expected},
• num_inference_steps must be positive, got {steps}
• Invalid {self.vae_scale_factor=}. Must be > 0.
• Invalid {self.patch_size=}. Must be > 0.
• head_dim must be a multiple of 8, got {head_dim}.

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