sgl-project/sglang · error · ValueError

mask_search_files_path is required for STA_tuning mode

Error message

mask_search_files_path is required for STA_tuning mode

What it means

In STA_tuning mode, configure_sta requires mask_search_files_path — the directory/files produced by a prior STA_searching run that tuning reads mask candidates from. The check uses truthiness (not just None), so an empty string also fails.

Source

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

            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)

        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)

View on GitHub (pinned to 0132848349)

Solutions

1. Run STA_searching first and pass its output directory, e.g. configure_sta('STA_tuning', mask_search_files_path='mask_candidates/', ...).
2. Verify the path exists and is non-empty before the call.
3. Fix kwarg spelling — exactly 'mask_search_files_path'.

Example fix

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

from pathlib import Path
p = Path(kwargs.get('mask_search_files_path') or '')
assert mode != 'STA_tuning' or (p.is_dir() and any(p.iterdir())), \
    "run STA_searching first and pass its output dir"

When it happens

Trigger: configure_sta('STA_tuning', ...) without mask_search_files_path, or with mask_search_files_path='' — kwargs.get returns None/empty.

Common situations: Running the tuning stage before the search stage has produced output; pointing at a wrong/empty path; YAML config leaving the field blank so it parses as empty string.

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_candidates is required for STA_tuning mode
• Usage: sglang serve --model-path <model-name-or-path> [addit
• Error: --model-path is required. Please provide the path to
• v_cache must be provided

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