sgl-project/sglang · error · ValueError

mask_search_files_path_pos, mask_search_files_path_neg, and

Error message

mask_search_files_path_pos, mask_search_files_path_neg, and save_dir are required for STA_tuning_cfg mode

What it means

configure_sta in STA_tuning_cfg mode requires three kwargs: mask_search_files_path_pos, mask_search_files_path_neg, and save_dir. The check uses truthiness, so None, empty string, or a missing key all trigger it. These paths point to positive/negative mask-search result JSON directories and where the tuned mask strategy will be written.

Source

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

        )

        return mask_strategy_3d
    elif mode == "STA_tuning_cfg":
        # Get required parameters for both positive and negative paths
        mask_search_files_path_pos: str | None = kwargs.get(
            "mask_search_files_path_pos"
        )
        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)

View on GitHub (pinned to 0132848349)

Solutions

1. Pass all three kwargs: mask_search_files_path_pos='<dir of pos JSON results>', mask_search_files_path_neg='<dir of neg JSON results>', save_dir='<output dir>'
2. Check for typos/whitespace in the kwarg names and ensure none resolve to empty strings from CLI/env defaults
3. Verify the pos/neg directories actually exist and contain the search-result JSON files before running

Example fix

# before
configure_sta(mode="STA_tuning_cfg", mask_search_files_path_pos=pos_dir)
# 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,
)

required = ["mask_search_files_path_pos", "mask_search_files_path_neg", "save_dir"]
missing = [k for k in required if not kwargs.get(k)]
assert not missing, f"missing STA_tuning_cfg kwargs: {missing}"

When it happens

Trigger: Calling configure_sta(mode='STA_tuning_cfg') (via prepare_sta_param) without passing mask_search_files_path_pos, mask_search_files_path_neg, or save_dir in kwargs, or passing any of them as '' or None.

Common situations: Running sparse-tuning-attention (STA) config generation where the caller copied an example that omitted the pos/neg search directories, or typos in kwarg names (e.g. mask_search_files_path instead of ..._pos/_neg), or an empty save_dir from an unset CLI arg.

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_candidates is required for STA_tuning_cfg mode
• 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/a26962feb9b528a9. Report an issue: GitHub.