{"record":{"id":"58f0cce5f68dd153","repo":"sgl-project/sglang","slug":"must-pass-a-value-for-mu-when-use-dynamic-shift","errorCode":null,"errorMessage":"Must pass a value for `mu` when `use_dynamic_shifting` is True","messagePattern":"Must pass a value for `mu` when `use_dynamic_shifting` is True","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/models/schedulers/hunyuan3d_scheduler.py","lineNumber":133,"sourceCode":"\n    def _sigma_to_t(self, sigma: float) -> float:\n        \"\"\"Convert sigma to timestep.\"\"\"\n        return sigma * self.config.num_train_timesteps\n\n    def time_shift(self, mu: float, sigma: float, t: torch.Tensor) -> torch.Tensor:\n        \"\"\"Apply time shift transformation.\"\"\"\n        return math.exp(mu) / (math.exp(mu) + (1 / t - 1) ** sigma)\n\n    def set_timesteps(\n        self,\n        num_inference_steps: int = None,\n        device: Union[str, torch.device] = None,\n        sigmas: Optional[List[float]] = None,\n        mu: Optional[float] = None,\n    ):\n        \"\"\"Set the discrete timesteps for the diffusion chain.\"\"\"\n        if self.config.use_dynamic_shifting and mu is None:\n            raise ValueError(\n                \"Must pass a value for `mu` when `use_dynamic_shifting` is True\"\n            )\n\n        if sigmas is None:\n            self.num_inference_steps = num_inference_steps\n            timesteps = np.linspace(\n                self._sigma_to_t(self.sigma_max),\n                self._sigma_to_t(self.sigma_min),\n                num_inference_steps,\n            )\n            sigmas = timesteps / self.config.num_train_timesteps\n\n        if self.config.use_dynamic_shifting:\n            sigmas = self.time_shift(mu, 1.0, sigmas)\n        else:\n            sigmas = self.config.shift * sigmas / (1 + (self.config.shift - 1) * sigmas)\n\n        sigmas = torch.from_numpy(sigmas).to(dtype=torch.float32, device=device)","sourceCodeStart":115,"sourceCodeEnd":151,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/models/schedulers/hunyuan3d_scheduler.py#L115-L151","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\nscheduler.set_timesteps(num_inference_steps=50)\n# after\nmu = calculate_shift_image_seq(1024)  # resolution-derived\nscheduler.set_timesteps(num_inference_steps=50, mu=mu)","handlingStrategy":"validation","validationCode":"if sched.config.use_dynamic_shifting and mu is None:\n    mu = calculate_shift_image_seq(token_count)  # pipeline-style\nsched.set_timesteps(num_inference_steps=steps, mu=mu)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always compute mu before set_timesteps when dynamic shifting is on","Recompute mu on resolution/token-count changes"],"tags":["scheduler","diffusion","missing-parameter","dynamic-shifting"],"backgroundTag":"missing-required-argument","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}