sgl-project/sglang · error · ValueError

mask_candidates is required for STA_searching mode

Error message

mask_candidates is required for STA_searching mode

What it means

In STA_searching mode, configure_sta requires the mask_candidates list (paths/names of candidate masks to search over) via kwargs; there is no default. Without it the mask-selection logic (which defaults mask_selected to all indices of mask_candidates) cannot proceed, so it raises.

Source

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

        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)
        masks_3d: list[list[list[list[int]]]] = []
        for i in range(time_step_num):  # Fixed t dimension = 50
            row = []
            for j in range(layer_num):  # Fixed l dimension = 60
                row.append(selected_masks)  # Add all masks at each position
            masks_3d.append(row)

View on GitHub (pinned to 0132848349)

Solutions

1. Pass mask_candidates as a list: configure_sta('STA_searching', mask_candidates=['mask_a.json', 'mask_b.json']).
2. Check spelling of the kwarg — it must be exactly 'mask_candidates'.
3. Validate required kwargs per mode before calling (see defense snippet).

Example fix

# before
params = configure_sta('STA_searching')
# after
params = configure_sta('STA_searching', mask_candidates=['m1.json','m2.json'])

if mode == "STA_searching":
    assert kwargs.get("mask_candidates"), "STA_searching requires mask_candidates"

When it happens

Trigger: configure_sta('STA_searching') or configure_sta('STA_searching', mask_selected=[0]) without mask_candidates — kwargs.get('mask_candidates') returns None.

Common situations: Building kwargs programmatically and the key is dropped/misspelled (mask_candidate, candidates); configs from YAML where the field is optional but the mode requires it.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• mask_candidates is required for STA_tuning mode
• mask_search_files_path is required for STA_tuning mode
• 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

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