sgl-project/sglang · error · ValueError

Must pass a value for `mu` when `use_dynamic_shifting` is Tr

Error message

Must pass a value for `mu` when `use_dynamic_shifting` is True

What it means

Hunyuan3D flow-match scheduler with use_dynamic_shifting=True computes sigmas via a resolution-dependent mu (as in diffusers SD3-style shifting), so set_timesteps requires mu each call. Omitting it makes sigma computation impossible and raises immediately.

Source

Thrown at python/sglang/multimodal_gen/runtime/models/schedulers/hunyuan3d_scheduler.py:133

    def _sigma_to_t(self, sigma: float) -> float:
        """Convert sigma to timestep."""
        return sigma * self.config.num_train_timesteps

    def time_shift(self, mu: float, sigma: float, t: torch.Tensor) -> torch.Tensor:
        """Apply time shift transformation."""
        return math.exp(mu) / (math.exp(mu) + (1 / t - 1) ** sigma)

    def set_timesteps(
        self,
        num_inference_steps: int = None,
        device: Union[str, torch.device] = None,
        sigmas: Optional[List[float]] = None,
        mu: Optional[float] = None,
    ):
        """Set the discrete timesteps for the diffusion chain."""
        if self.config.use_dynamic_shifting and mu is None:
            raise ValueError(
                "Must pass a value for `mu` when `use_dynamic_shifting` is True"
            )

        if sigmas is None:
            self.num_inference_steps = num_inference_steps
            timesteps = np.linspace(
                self._sigma_to_t(self.sigma_max),
                self._sigma_to_t(self.sigma_min),
                num_inference_steps,
            )
            sigmas = timesteps / self.config.num_train_timesteps

        if self.config.use_dynamic_shifting:
            sigmas = self.time_shift(mu, 1.0, sigmas)
        else:
            sigmas = self.config.shift * sigmas / (1 + (self.config.shift - 1) * sigmas)

        sigmas = torch.from_numpy(sigmas).to(dtype=torch.float32, device=device)

View on GitHub (pinned to 0132848349)

Solutions

Compute and pass mu, e.g. mu = calculate_shift(unet/transformer sequence length) as the pipeline does
If dynamic shifting is not needed, set use_dynamic_shifting=False in the scheduler config
Pass mu on every set_timesteps call when image resolution changes

Example fix

# before
scheduler.set_timesteps(num_inference_steps=50)
# after
mu = calculate_shift_image_seq(1024)  # resolution-derived
scheduler.set_timesteps(num_inference_steps=50, mu=mu)

Defensive patterns

Strategy: validation

Validate before calling

if sched.config.use_dynamic_shifting and mu is None:
    mu = calculate_shift_image_seq(token_count)  # pipeline-style
sched.set_timesteps(num_inference_steps=steps, mu=mu)

Prevention

Always compute mu before set_timesteps when dynamic shifting is on
Recompute mu on resolution/token-count changes

When it happens

Trigger: Calling scheduler.set_timesteps(50) with config.use_dynamic_shifting=True and no mu argument; typically mu is computed from (H*W*C / base) style sequence-length ratios by the pipeline and must be passed through.

Common situations: Using the scheduler standalone instead of through the pipeline that computes mu; diffusers version differences where the pipeline signature changed; resolution changes making the pipeline forget to recompute mu.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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