{"record":{"id":"7589f10c4c89ce62","repo":"sgl-project/sglang","slug":"mask-candidates-is-required-for-sta-tuning-cfg-mod","errorCode":null,"errorMessage":"mask_candidates is required for STA_tuning_cfg mode","messagePattern":"mask_candidates is required for STA_tuning_cfg mode","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/layers/attention/STA_configuration.py","lineNumber":171,"sourceCode":"        )\n        mask_search_files_path_neg: str | None = kwargs.get(\n            \"mask_search_files_path_neg\"\n        )\n        save_dir_cfg: str | None = kwargs.get(\"save_dir\")\n\n        if (\n            not mask_search_files_path_pos\n            or not mask_search_files_path_neg\n            or not save_dir_cfg\n        ):\n            raise ValueError(\n                \"mask_search_files_path_pos, mask_search_files_path_neg, and save_dir are required for STA_tuning_cfg mode\"\n            )\n\n        # Get optional parameters with defaults\n        mask_candidates_cfg: list[str] | None = kwargs.get(\"mask_candidates\")\n        if mask_candidates_cfg is None:\n            raise ValueError(\"mask_candidates is required for STA_tuning_cfg mode\")\n        mask_selected_cfg: list[int] = kwargs.get(\n            \"mask_selected\", list(range(len(mask_candidates_cfg)))\n        )\n        skip_time_steps_cfg: int | None = kwargs.get(\"skip_time_steps\")\n\n        # Parse selected masks\n        selected_masks_cfg: list[list[int]] = []\n        for index in mask_selected_cfg:\n            mask = mask_candidates_cfg[index]\n            masks_list = [int(x) for x in mask.split(\",\")]\n            selected_masks_cfg.append(masks_list)\n\n        # Read JSON results for both positive and negative paths\n        pos_results = read_specific_json_files(mask_search_files_path_pos)\n        neg_results = read_specific_json_files(mask_search_files_path_neg)\n        # Combine positive and negative results into one list\n        combined_results = pos_results + neg_results\n","sourceCodeStart":153,"sourceCodeEnd":189,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/layers/attention/STA_configuration.py#L153-L189","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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']","Ensure the upstream config (model STA config / prepare_sta_param caller) actually defines mask_candidates before selecting this mode","If you only want the default all-selected behavior, still pass the list; mask_selected defaults to range(len(mask_candidates))]"],"exampleFix":"# before\nconfigure_sta(mode=\"STA_tuning_cfg\", ..., mask_candidates=None)\n# after\nconfigure_sta(\n    mode=\"STA_tuning_cfg\",\n    mask_search_files_path_pos=pos_dir,\n    mask_search_files_path_neg=neg_dir,\n    save_dir=out_dir,\n    mask_candidates=[\"1,2,4,8,16,32,64,128,256,512,1024\"],\n)","handlingStrategy":"validation","validationCode":"mc = kwargs.get(\"mask_candidates\")\nassert mc, \"mask_candidates must be a non-empty list for STA_tuning_cfg\"","typeGuard":"def is_mask_candidates(v) -> bool:\n    return isinstance(v, list) and len(v) > 0 and all(isinstance(s, str) and \",\" in s for s in v)","tryCatchPattern":null,"preventionTips":["Keep mask_candidates in the model STA config file so it cannot be omitted","Validate non-empty list, not just non-None, since [] passes the None check but breaks later"],"tags":["sta","attention","sparse-tuning","kwargs-validation"],"backgroundTag":"missing-required-argument","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}