sgl-project/sglang · error · ValueError

load_path is required for STA_inference mode

Error message

load_path is required for STA_inference mode

What it means

In STA_inference mode configure_sta loads a previously tuned mask strategy from load_path (default 'mask_candidates/mask_strategy.json'). Only an explicit None (kwargs['load_path']=None) triggers this error, since the default kicks in when the key is absent. After the check it open()s the file, so a bad path will instead raise FileNotFoundError.

Source

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

        print("\nStrategy usage counts:")
        total_heads = time_step_num * layer_num * head_num  # Fixed dimensions
        for strategy, count in strategy_counts.items():
            print(f"Strategy {strategy}: {count} heads ({count/total_heads*100:.2f}%)")

        # Convert dictionary to 3D list with fixed dimensions
        mask_strategy_3d = dict_to_3d_list(
            mask_strategy, t_max=time_step_num, l_max=layer_num, h_max=head_num
        )

        return mask_strategy_3d

    else:  # STA_inference
        # Get parameters with defaults
        load_path: str | None = kwargs.get(
            "load_path", "mask_candidates/mask_strategy.json"
        )
        if load_path is None:
            raise ValueError("load_path is required for STA_inference mode")

        # Load previously saved mask strategy
        with open(load_path) as f:
            mask_strategy = json.load(f)

        # Convert dictionary to 3D list with fixed dimensions
        mask_strategy_3d = dict_to_3d_list(
            mask_strategy, t_max=time_step_num, l_max=layer_num, h_max=head_num
        )

        return mask_strategy_3d


# Helper functions


def read_specific_json_files(folder_path: str) -> list[dict[str, Any]]:
    """Read and parse JSON files containing mask search results."""

View on GitHub (pinned to 0132848349)

Solutions

1. Pass a real path: load_path='<path to mask_strategy.json produced by a tuning run>'
2. If the field is optional in your config, only include load_path in kwargs when it is non-null (don't pass None)
3. Run the STA_tuning / STA_tuning_cfg mode first to generate mask_strategy.json, then point load_path at it

Example fix

# before
configure_sta(mode="STA_inference", load_path=cfg.get("load_path"))  # cfg lacks the key -> None
# after
kwargs = {"load_path": cfg["load_path"]} if cfg.get("load_path") else {}
configure_sta(mode="STA_inference", **kwargs)

lp = cfg.get("load_path")
sta_kwargs = {"load_path": lp} if lp else {}
configure_sta(mode="STA_inference", **sta_kwargs)

When it happens

Trigger: Calling configure_sta(mode='STA_inference') or any non-tuning mode with load_path explicitly set to None in kwargs. Merely omitting load_path uses the default 'mask_candidates/mask_strategy.json' and does not raise this.

Common situations: A config loader that reads load_path from a YAML/JSON config where the field is absent and null is forwarded verbatim; or code that conditionally builds kwargs and passes load_path=None when the user gave no value.

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
• mask_candidates is required for STA_tuning_cfg 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/0b42c7720443b015. Report an issue: GitHub.