sgl-project/sglang · error · ValueError

source must be 'timesteps' or 'sigmas'

Error message

source must be 'timesteps' or 'sigmas'

What it means

_dual_sigma_shift is keyword-only parametrized by source, which tells it whether the pairs represent timesteps or sigmas (the transform differs). Passing anything other than the literal strings 'timesteps' or 'sigmas' (including None, 'Timesteps', 'sigma', or typos) raises ValueError.

Source

Thrown at python/sglang/multimodal_gen/runtime/models/schedulers/flow_match_pair.py:373

            audio_denoising_strength = float(
                kwargs.get("audio_denoising_strength", 1.0)
            )
            visual_mu = kwargs.get(
                "visual_exponential_shift_mu", self.exponential_shift_mu
            )
            audio_mu = kwargs.get(
                "audio_exponential_shift_mu", self.exponential_shift_mu
            )

            def _dual_sigma_shift(pairs: torch.Tensor, *, source: str):
                if not isinstance(pairs, torch.Tensor):
                    raise TypeError("pairs must be a torch.Tensor")
                if pairs.ndim != 2 or pairs.shape[1] != 2:
                    raise ValueError("pairs must be a torch.Tensor of shape [N, 2]")
                if pairs.shape[0] == 0:
                    raise ValueError("pairs length must be greater than 0")
                if source not in ("timesteps", "sigmas"):
                    raise ValueError("source must be 'timesteps' or 'sigmas'")

                num_steps = pairs.shape[0]
                device = pairs.device
                dtype = pairs.dtype

                def _build_column(
                    shift_value: float, denoising_strength: float, mu_override
                ):
                    if shift_value <= 0:
                        raise ValueError("shift must be positive")
                    if denoising_strength <= 0:
                        raise ValueError("denoising_strength must be positive")

                    sigma_start = (
                        self.sigma_min
                        + (self.sigma_max - self.sigma_min) * denoising_strength
                    )
                    if self.extra_one_step:

View on GitHub (pinned to 0132848349)

Solutions

1. Pass the exact keyword: source="timesteps" if pairs came from the timestep schedule, source="sigmas" if from sigma schedule
2. Check the scheduler's docstring/constants for the accepted values and use those literals (no uppercase/abbreviations)
3. Centralize the string in one constant shared with the scheduler to avoid drift
4. Default explicitly in your wrapper: source = source or 'sigmas' based on which cache you read

Example fix

# before
result = postprocess(pairs, source="sigma")

# after
result = postprocess(pairs, source="sigmas")

VALID_SOURCES = ("timesteps", "sigmas")
if source not in VALID_SOURCES:
    raise ValueError(f"source must be one of {VALID_SOURCES}, got {source!r}")

def is_valid_source(s) -> TypeGuard[str]:
    return s in ("timesteps", "sigmas")

When it happens

Trigger: Calling the postprocess / step API with source omitted where no default exists, or passing a variant spelling like 'sigma', 'TIMESTEPS', or an enum. Typically happens when a caller copies code from a different scheduler version whose API used different source names.

Common situations: API drift between scheduler versions (renamed or newly required keyword); caller passes None because it doesn't know which representation the pairs use; string constants duplicated across the codebase drifting out of sync.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• pairs must be a torch.Tensor
• pairs length must be greater than 0
• shift must be positive
• missing `sample` as a required keyword argument
• missing `order` as a required keyword argument

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