sgl-project/sglang · error · ValueError

mask_candidates is required for STA_tuning mode

Error message

mask_candidates is required for STA_tuning mode

What it means

In STA_tuning mode, besides mask_search_files_path, configure_sta also requires the mask_candidates list naming which candidate masks to tune. mask_selected defaults to all indices of this list, so the list must be present.

Source

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

        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)

        return masks_3d

    elif mode == "STA_tuning":
        # Get required parameters
        mask_search_files_path: str | None = kwargs.get("mask_search_files_path")
        if not mask_search_files_path:
            raise ValueError("mask_search_files_path is required for STA_tuning mode")

        # Get optional parameters with defaults
        mask_candidates_tuning: list[str] | None = kwargs.get("mask_candidates")
        if mask_candidates_tuning is None:
            raise ValueError("mask_candidates is required for STA_tuning mode")
        mask_selected_tuning: list[int] = kwargs.get(
            "mask_selected", list(range(len(mask_candidates_tuning)))
        )
        skip_time_steps_tuning: int | None = kwargs.get("skip_time_steps")
        save_dir_tuning: str | None = kwargs.get("save_dir", "mask_candidates")

        # Parse selected masks
        selected_masks_tuning: list[list[int]] = []
        for index in mask_selected_tuning:
            mask = mask_candidates_tuning[index]
            masks_list = [int(x) for x in mask.split(",")]
            selected_masks_tuning.append(masks_list)

        # Read JSON results
        results = read_specific_json_files(mask_search_files_path)
        averaged_results = average_head_losses(results, selected_masks_tuning)

        # Add full attention mask for specific cases

View on GitHub (pinned to 0132848349)

Solutions

1. Pass mask_candidates explicitly: configure_sta('STA_tuning', mask_search_files_path=..., mask_candidates=[...]).
2. Ensure names match the files produced by the searching stage.
3. Pre-validate required kwargs for STA_tuning (both mask_search_files_path and mask_candidates) before calling.

Example fix

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

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

When it happens

Trigger: configure_sta('STA_tuning', mask_search_files_path='...') with no mask_candidates kwarg — kwargs.get('mask_candidates') is None at STA_configuration.py:91.

Common situations: Assuming tuning reads candidates implicitly from the search directory and omitting the list; kwargs typos; config templates copied from STA_inference examples that don't include mask_candidates.

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_searching 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/493ebf5daa3cba47. Report an issue: GitHub.