{"record":{"id":"4dfdf6d85ecaf364","repo":"sgl-project/sglang","slug":"unknown-residency-policy-policy-r-for-component","errorCode":null,"errorMessage":"unknown residency policy {policy!r} for component {component_name!r}, expected one of {RESIDENCY_POLICIES}","messagePattern":"unknown residency policy (.+?) for component (.+?), expected one of (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/server_args/server_args.py","lineNumber":1087,"sourceCode":"            self.layerwise_residency_policy, option=\"--layerwise-residency-policy\"\n        )\n\n        def _pick(mapping: dict[str, str], group_default, aux_default):\n            if component_name is not None and component_name in mapping:\n                return mapping[component_name]\n            return group_default if dit_group else aux_default\n\n        prefetch = float(_pick(prefetch_map, self.dit_offload_prefetch_size, 0.0))\n        resident = float(_pick(resident_map, self.dit_layerwise_resident_layers, 0.0))\n        policy = str(\n            _pick(\n                policy_map,\n                self.dit_layerwise_residency_policy,\n                RESIDENCY_POLICY_LEADING,\n            )\n        )\n        if policy not in RESIDENCY_POLICIES:\n            raise ValueError(\n                f\"unknown residency policy {policy!r} for component \"\n                f\"{component_name!r}, expected one of {RESIDENCY_POLICIES}\"\n            )\n        return prefetch, resident, policy\n\n    @staticmethod\n    def _parse_component_attention_backend_map(\n        value: dict[str, str] | str | None,\n    ) -> dict[str, str]:\n        if value is None or value == \"\":\n            return {}\n        if isinstance(value, dict):\n            return dict(value)\n        if not isinstance(value, str):\n            raise ValueError(\n                \"component_attention_backends must be a dict or a comma-separated component=backend string\"\n            )\n","sourceCodeStart":1069,"sourceCodeEnd":1105,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/server_args/server_args.py#L1069-L1105","documentation":"layerwise_tuning_for() resolves the residency policy for a component from the per-component map plus a leading/default policy, then validates it against the known RESIDENCY_POLICIES set. An unrecognized policy string (typo, wrong casing, unsupported mode) is rejected immediately because downstream offload logic can only handle known policies.","triggerScenarios":"Calling server_args.layerwise_tuning_for('dit', dit_group=True) when the effective policy resolves to e.g. 'offload' or 'layer_wise' (misspelled) instead of a member of RESIDENCY_POLICIES; passing --dit-layerwise-residency-policy dit=foo.","commonSituations":"Policy renamed across versions; copying policy names from older docs or other flags; using underscores/hyphens inconsistently; tests exercising rejection of unknown policies.","solutions":["Print RESIDENCY_POLICIES (import from the server_args module) and use an exact member","Fix the typo in the component=policy entry or the leading default policy","Upgrade/downgrade docs alignment: check the version's supported policy names"],"exampleFix":"# before\n--dit-layerwise-residency-policy dit=layerwise\n# after\n--dit-layerwise-residency-policy dit=layerwise_offload","handlingStrategy":"validation","validationCode":"from sglang.multimodal_gen.runtime.server_args.server_args import RESIDENCY_POLICIES\npolicy = args.layerwise_tuning_for('dit', dit_group=True)\n# pre-check any user-supplied policy:\nassert user_policy in RESIDENCY_POLICIES, f'policy must be one of {RESIDENCY_POLICIES}'","typeGuard":"def is_valid_policy(p: str) -> bool:\n    return p in RESIDENCY_POLICIES","tryCatchPattern":"try:\n    prefetch, resident, policy = args.layerwise_tuning_for(name, dit_group=True)\nexcept ValueError as e:\n    if 'unknown residency policy' in str(e):\n        policy = 'resident'  # fallback default\n    else:\n        raise","preventionTips":["Expose RESIDENCY_POLICIES in validation UIs","Fail fast on unknown policy strings at config load"],"tags":["config","validation","layerwise-offload","residency"],"backgroundTag":"invalid-enum-value","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}