{"record":{"id":"37a347ff4d6f829d","repo":"sgl-project/sglang","slug":"feature-name-requires-component-name-r-to-be-r","errorCode":null,"errorMessage":"{feature_name} requires {component_name!r} to be resident; got {configured_mode!r} from --component-residency","messagePattern":"(.+?) requires (.+?) to be resident; got (.+?) from --component-residency","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/server_args/server_args.py","lineNumber":1545,"sourceCode":"        if is_vae_component_name(component_name):\n            return COMPONENT_OFFLOAD if self.vae_cpu_offload else RESIDENT\n        return RESIDENT\n\n    def should_cpu_offload_component(self, component_name: str) -> bool:\n        return self.residency_mode(component_name) == COMPONENT_OFFLOAD\n\n    def should_start_component_on_cpu(self, component_name: str) -> bool:\n        return self.residency_mode(component_name) in (\n            COMPONENT_OFFLOAD,\n            LAYERWISE_OFFLOAD,\n        )\n\n    def require_component_resident(\n        self, component_name: str, *, feature_name: str\n    ) -> None:\n        configured_mode = self.canonical_residency_mode(component_name)\n        if configured_mode is not None and configured_mode != RESIDENT:\n            raise ValueError(\n                f\"{feature_name} requires {component_name!r} to be resident; \"\n                f\"got {configured_mode!r} from --component-residency\"\n            )\n        self._required_resident_components.add(component_name)\n\n    def should_use_fsdp_for_component(self, component_name: str) -> bool:\n        return bool(\n            self.use_fsdp_inference\n            and component_name not in self._fsdp_disabled_components\n            and self.residency_mode(component_name) == RESIDENT\n        )\n\n    def disable_fsdp_for_component(self, component_name: str) -> None:\n        self._fsdp_disabled_components.add(component_name)\n\n    def record_component_layerwise_capability(\n        self, component_name: str, *, supported: bool\n    ) -> None:","sourceCodeStart":1527,"sourceCodeEnd":1563,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/server_args/server_args.py#L1527-L1563","documentation":"require_component_resident() is called by features (native load, model load, NVFP4 fallback, offload-mode adjustment) that need a component fully resident in GPU memory. If --component-residency configured a non-resident mode for that component, the feature aborts.","triggerScenarios":"Enabling e.g. NVFP4 quantization fallback or a native-load path while --component-residency dit=layerwise_offload; the feature then calls require_component_resident('dit', feature_name=...).","commonSituations":"Combining quantized-load paths with layerwise/block offload to save VRAM; flags added independently by different team members; defaults flipped to offload under memory pressure.","solutions":["Set the component to resident: --component-residency dit=resident (or remove the override)","Disable the feature that requires residency (e.g. the NVFP4 fallback / offload-adjustment path)","Free VRAM another way (smaller batch, shorter seqs) so resident mode fits"],"exampleFix":"# before\n--component-residency dit=layerwise_offload --load-native\n# after\n--component-residency dit=resident --load-native","handlingStrategy":"validation","validationCode":"mode = args.canonical_residency_mode('dit')\nassert mode is None or mode == 'resident', f'feature needs dit resident, got {mode}'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Check residency before enabling residency-dependent features","Encode feature/flag compatibility matrix in config validation"],"tags":["config","residency","feature-conflict"],"backgroundTag":"mutually-exclusive-options","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}