sgl-project/sglang · error · ValueError

mask_candidates is required for STA_tuning_cfg mode

Error message

mask_candidates is required for STA_tuning_cfg mode

What it means

In STA_tuning_cfg mode, configure_sta additionally requires mask_candidates (a list of comma-separated mask spec strings). Unlike the other params it has no default and the code indexes into it via mask_selected, so a None value fails fast with this ValueError.

Source

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

        )
        mask_search_files_path_neg: str | None = kwargs.get(
            "mask_search_files_path_neg"
        )
        save_dir_cfg: str | None = kwargs.get("save_dir")

        if (
            not mask_search_files_path_pos
            or not mask_search_files_path_neg
            or not save_dir_cfg
        ):
            raise ValueError(
                "mask_search_files_path_pos, mask_search_files_path_neg, and save_dir are required for STA_tuning_cfg mode"
            )

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

        # Parse selected masks
        selected_masks_cfg: list[list[int]] = []
        for index in mask_selected_cfg:
            mask = mask_candidates_cfg[index]
            masks_list = [int(x) for x in mask.split(",")]
            selected_masks_cfg.append(masks_list)

        # Read JSON results for both positive and negative paths
        pos_results = read_specific_json_files(mask_search_files_path_pos)
        neg_results = read_specific_json_files(mask_search_files_path_neg)
        # Combine positive and negative results into one list
        combined_results = pos_results + neg_results

View on GitHub (pinned to 0132848349)

Solutions

1. Pass mask_candidates as a non-empty list of mask spec strings, e.g. ['1,2,4,8,16,32,64,128,256,512,1024']
2. Ensure the upstream config (model STA config / prepare_sta_param caller) actually defines mask_candidates before selecting this mode
3. If you only want the default all-selected behavior, still pass the list; mask_selected defaults to range(len(mask_candidates))]

Example fix

# before
configure_sta(mode="STA_tuning_cfg", ..., mask_candidates=None)
# after
configure_sta(
    mode="STA_tuning_cfg",
    mask_search_files_path_pos=pos_dir,
    mask_search_files_path_neg=neg_dir,
    save_dir=out_dir,
    mask_candidates=["1,2,4,8,16,32,64,128,256,512,1024"],
)

mc = kwargs.get("mask_candidates")
assert mc, "mask_candidates must be a non-empty list for STA_tuning_cfg"

def is_mask_candidates(v) -> bool:
    return isinstance(v, list) and len(v) > 0 and all(isinstance(s, str) and "," in s for s in v)

When it happens

Trigger: Calling configure_sta(mode='STA_tuning_cfg') with the three path kwargs but omitting mask_candidates from kwargs (kwargs.get('mask_candidates') returns None). Note: passing an empty list [] passes the None check but will fail later when mask_selected indexes it.

Common situations: The mask_candidates list normally comes from the model's STA config; if the config file lacks a mask_candidates entry or the caller forwards only a subset of kwargs, this fires.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• mask_search_files_path_pos, mask_search_files_path_neg, and
• load_path is required for STA_inference mode
• Mode must be one of {valid_modes}, got {mode}
• mask_candidates is required for STA_searching mode
• mask_candidates is required for STA_tuning mode

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