sgl-project/sglang · error · ValueError

Mode must be one of {valid_modes}, got {mode}

Error message

Mode must be one of {valid_modes}, got {mode}

What it means

configure_sta configures Sparse-Triangle-Attention modes and only accepts four modes: STA_searching, STA_tuning, STA_inference, STA_tuning_cfg. Passing any other mode string raises immediately, before any kwargs are read.

Source

Thrown at python/sglang/multimodal_gen/runtime/layers/attention/STA_configuration.py:54

        Mode-specific parameters:

        For 'STA_searching':
        - mask_candidates: list of str, optional, mask candidates to use
        - mask_selected: list of int, optional, indices of selected masks

        For 'STA_tuning':
        - mask_search_files_path: str, required, path to mask search results
        - mask_candidates: list of str, optional, mask candidates to use
        - mask_selected: list of int, optional, indices of selected masks
        - skip_time_steps: int, optional, number of time steps to use full attention (default 12)
        - save_dir: str, optional, directory to save mask strategy (default "mask_candidates")

        For 'STA_inference':
        - load_path: str, optional, path to load mask strategy (default "mask_candidates/mask_strategy.json")
    """
    valid_modes = ["STA_searching", "STA_tuning", "STA_inference", "STA_tuning_cfg"]
    if mode not in valid_modes:
        raise ValueError(f"Mode must be one of {valid_modes}, got {mode}")

    if mode == "STA_searching":
        # Get parameters with defaults
        mask_candidates: list[str] | None = kwargs.get("mask_candidates")
        if mask_candidates is None:
            raise ValueError("mask_candidates is required for STA_searching mode")
        mask_selected: list[int] = kwargs.get(
            "mask_selected", list(range(len(mask_candidates)))
        )

        # Parse selected masks
        selected_masks: list[list[int]] = []
        for index in mask_selected:
            mask = mask_candidates[index]
            masks_list = [int(x) for x in mask.split(",")]
            selected_masks.append(masks_list)

        # Create 3D mask structure with fixed dimensions (t=50, l=60)

View on GitHub (pinned to 0132848349)

Solutions

1. Use exactly one of: 'STA_searching', 'STA_tuning', 'STA_inference', 'STA_tuning_cfg' (case-sensitive).
2. If adding a new mode, append it to valid_modes and implement its branch.
3. Normalize/validate mode strings at the call site before invoking configure_sta.

Example fix

# before
params = configure_sta('sta_searching', mask_candidates=[...])
# after
params = configure_sta('STA_searching', mask_candidates=[...])

VALID_STA_MODES = {"STA_searching","STA_tuning","STA_inference","STA_tuning_cfg"}
assert mode in VALID_STA_MODES, f"mode must be one of {VALID_STA_MODES}"

def is_valid_sta_mode(mode: str) -> bool:
    return mode in {"STA_searching","STA_tuning","STA_inference","STA_tuning_cfg"}

When it happens

Trigger: Calling configure_sta(mode, **kwargs) with a typo'd or unsupported mode, e.g. 'sta_searching' (lowercase), 'STA_search', or a newly added mode not in the valid_modes list at STA_configuration.py:54.

Common situations: Case/typo mismatches with the exact enum-like strings; code copied from docs of a different version; extending STA with a new mode without updating valid_modes.

Related errors

• mask_search_files_path_pos, mask_search_files_path_neg, and
• mask_candidates is required for STA_tuning_cfg mode
• load_path is required for STA_inference mode
• Replicated Q, K, and V must be provided together.
• num_heads must be divisible by num_epi_subtiles

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