{"record":{"id":"493ebf5daa3cba47","repo":"sgl-project/sglang","slug":"mask-candidates-is-required-for-sta-tuning-mode","errorCode":null,"errorMessage":"mask_candidates is required for STA_tuning mode","messagePattern":"mask_candidates is required for STA_tuning mode","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/layers/attention/STA_configuration.py","lineNumber":91,"sourceCode":"        masks_3d: list[list[list[list[int]]]] = []\n        for i in range(time_step_num):  # Fixed t dimension = 50\n            row = []\n            for j in range(layer_num):  # Fixed l dimension = 60\n                row.append(selected_masks)  # Add all masks at each position\n            masks_3d.append(row)\n\n        return masks_3d\n\n    elif mode == \"STA_tuning\":\n        # Get required parameters\n        mask_search_files_path: str | None = kwargs.get(\"mask_search_files_path\")\n        if not mask_search_files_path:\n            raise ValueError(\"mask_search_files_path is required for STA_tuning mode\")\n\n        # Get optional parameters with defaults\n        mask_candidates_tuning: list[str] | None = kwargs.get(\"mask_candidates\")\n        if mask_candidates_tuning is None:\n            raise ValueError(\"mask_candidates is required for STA_tuning mode\")\n        mask_selected_tuning: list[int] = kwargs.get(\n            \"mask_selected\", list(range(len(mask_candidates_tuning)))\n        )\n        skip_time_steps_tuning: int | None = kwargs.get(\"skip_time_steps\")\n        save_dir_tuning: str | None = kwargs.get(\"save_dir\", \"mask_candidates\")\n\n        # Parse selected masks\n        selected_masks_tuning: list[list[int]] = []\n        for index in mask_selected_tuning:\n            mask = mask_candidates_tuning[index]\n            masks_list = [int(x) for x in mask.split(\",\")]\n            selected_masks_tuning.append(masks_list)\n\n        # Read JSON results\n        results = read_specific_json_files(mask_search_files_path)\n        averaged_results = average_head_losses(results, selected_masks_tuning)\n\n        # Add full attention mask for specific cases","sourceCodeStart":73,"sourceCodeEnd":109,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/layers/attention/STA_configuration.py#L73-L109","documentation":"In STA_tuning mode, besides mask_search_files_path, configure_sta also requires the mask_candidates list naming which candidate masks to tune. mask_selected defaults to all indices of this list, so the list must be present.","triggerScenarios":"configure_sta('STA_tuning', mask_search_files_path='...') with no mask_candidates kwarg — kwargs.get('mask_candidates') is None at STA_configuration.py:91.","commonSituations":"Assuming tuning reads candidates implicitly from the search directory and omitting the list; kwargs typos; config templates copied from STA_inference examples that don't include mask_candidates.","solutions":["Pass mask_candidates explicitly: configure_sta('STA_tuning', mask_search_files_path=..., mask_candidates=[...]).","Ensure names match the files produced by the searching stage.","Pre-validate required kwargs for STA_tuning (both mask_search_files_path and mask_candidates) before calling."],"exampleFix":"# before\nparams = configure_sta('STA_tuning', mask_search_files_path='mask_candidates/')\n# after\nparams = configure_sta('STA_tuning', mask_search_files_path='mask_candidates/',\n                       mask_candidates=['m1.json','m2.json'])","handlingStrategy":"validation","validationCode":"if mode == \"STA_tuning\":\n    assert kwargs.get(\"mask_candidates\"), \"STA_tuning requires mask_candidates\"\n    assert kwargs.get(\"mask_search_files_path\"), \"STA_tuning requires mask_search_files_path\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate the full STA_tuning kwarg set in one preflight helper.","Derive mask_candidates from the searching-stage output dir to keep names in sync."],"tags":["sta","missing-argument","kwargs-validation"],"backgroundTag":"missing-required-parameter","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}