{"record":{"id":"1a341dc3377aff3e","repo":"sgl-project/sglang","slug":"mask-search-files-path-is-required-for-sta-tuning","errorCode":null,"errorMessage":"mask_search_files_path is required for STA_tuning mode","messagePattern":"mask_search_files_path 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":86,"sourceCode":"            mask = mask_candidates[index]\n            masks_list = [int(x) for x in mask.split(\",\")]\n            selected_masks.append(masks_list)\n\n        # Create 3D mask structure with fixed dimensions (t=50, l=60)\n        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","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/layers/attention/STA_configuration.py#L68-L104","documentation":"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.","triggerScenarios":"configure_sta('STA_tuning', ...) without mask_search_files_path, or with mask_search_files_path='' — kwargs.get returns None/empty.","commonSituations":"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.","solutions":["Run STA_searching first and pass its output directory, e.g. configure_sta('STA_tuning', mask_search_files_path='mask_candidates/', ...).","Verify the path exists and is non-empty before the call.","Fix kwarg spelling — exactly 'mask_search_files_path'."],"exampleFix":"# before\nparams = configure_sta('STA_tuning', mask_candidates=[...])\n# after\nparams = configure_sta('STA_tuning', mask_search_files_path='mask_candidates/',\n                       mask_candidates=[...])","handlingStrategy":"validation","validationCode":"from pathlib import Path\np = Path(kwargs.get('mask_search_files_path') or '')\nassert mode != 'STA_tuning' or (p.is_dir() and any(p.iterdir())), \\\n    \"run STA_searching first and pass its output dir\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Enforce pipeline order: searching → tuning; verify search output exists before tuning.","Reject empty-string path values in configs before they reach configure_sta."],"tags":["sta","missing-argument","file-path","pipeline-ordering"],"backgroundTag":"missing-required-parameter","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}