{"record":{"id":"5c20ae8024b4cc9e","repo":"sgl-project/sglang","slug":"mask-candidates-is-required-for-sta-searching-mode","errorCode":null,"errorMessage":"mask_candidates is required for STA_searching mode","messagePattern":"mask_candidates is required for STA_searching mode","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/layers/attention/STA_configuration.py","lineNumber":60,"sourceCode":"        For 'STA_tuning':\n        - mask_search_files_path: str, required, path to mask search results\n        - mask_candidates: list of str, optional, mask candidates to use\n        - mask_selected: list of int, optional, indices of selected masks\n        - skip_time_steps: int, optional, number of time steps to use full attention (default 12)\n        - save_dir: str, optional, directory to save mask strategy (default \"mask_candidates\")\n\n        For 'STA_inference':\n        - load_path: str, optional, path to load mask strategy (default \"mask_candidates/mask_strategy.json\")\n    \"\"\"\n    valid_modes = [\"STA_searching\", \"STA_tuning\", \"STA_inference\", \"STA_tuning_cfg\"]\n    if mode not in valid_modes:\n        raise ValueError(f\"Mode must be one of {valid_modes}, got {mode}\")\n\n    if mode == \"STA_searching\":\n        # Get parameters with defaults\n        mask_candidates: list[str] | None = kwargs.get(\"mask_candidates\")\n        if mask_candidates is None:\n            raise ValueError(\"mask_candidates is required for STA_searching mode\")\n        mask_selected: list[int] = kwargs.get(\n            \"mask_selected\", list(range(len(mask_candidates)))\n        )\n\n        # Parse selected masks\n        selected_masks: list[list[int]] = []\n        for index in mask_selected:\n            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)","sourceCodeStart":42,"sourceCodeEnd":78,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/layers/attention/STA_configuration.py#L42-L78","documentation":"In STA_searching mode, configure_sta requires the mask_candidates list (paths/names of candidate masks to search over) via kwargs; there is no default. Without it the mask-selection logic (which defaults mask_selected to all indices of mask_candidates) cannot proceed, so it raises.","triggerScenarios":"configure_sta('STA_searching') or configure_sta('STA_searching', mask_selected=[0]) without mask_candidates — kwargs.get('mask_candidates') returns None.","commonSituations":"Building kwargs programmatically and the key is dropped/misspelled (mask_candidate, candidates); configs from YAML where the field is optional but the mode requires it.","solutions":["Pass mask_candidates as a list: configure_sta('STA_searching', mask_candidates=['mask_a.json', 'mask_b.json']).","Check spelling of the kwarg — it must be exactly 'mask_candidates'.","Validate required kwargs per mode before calling (see defense snippet)."],"exampleFix":"# before\nparams = configure_sta('STA_searching')\n# after\nparams = configure_sta('STA_searching', mask_candidates=['m1.json','m2.json'])","handlingStrategy":"validation","validationCode":"if mode == \"STA_searching\":\n    assert kwargs.get(\"mask_candidates\"), \"STA_searching requires mask_candidates\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Build mode-specific required-kwarg checklists and validate before calling configure_sta.","Use exact kwarg names from the docstring; avoid programmatic kwargs without key checks."],"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"}