{"record":{"id":"ce62a6ee51eec1c0","repo":"sgl-project/sglang","slug":"dynamic-hicache-sidecars-require-hostpoolgroup","errorCode":null,"errorMessage":"Dynamic HiCache sidecars require HostPoolGroup.","messagePattern":"Dynamic HiCache sidecars require HostPoolGroup\\.","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/mem_cache/hybrid_cache/hybrid_cache_controller.py","lineNumber":173,"sourceCode":"        storage_backend: str,\n        prefetch_threshold: int = 256,\n        model_name: Optional[str] = None,\n        storage_backend_extra_config: Optional[dict] = None,\n        host_pools: Optional[list[PoolEntry]] = None,\n    ):\n        super().attach_storage_backend(\n            storage_backend=storage_backend,\n            prefetch_threshold=prefetch_threshold,\n            model_name=model_name,\n            storage_backend_extra_config=storage_backend_extra_config,\n        )\n\n        for entry in host_pools or []:\n            self.storage_backend.register_mem_host_pool_v2(entry.host_pool, entry.name)\n\n    def register_host_pool_entry(self, entry: PoolEntry) -> None:\n        if not isinstance(self.mem_pool_host, HostPoolGroup):\n            raise TypeError(\"Dynamic HiCache sidecars require HostPoolGroup.\")\n        self.mem_pool_host.add_entry(entry)\n        if not entry.is_primary_index_anchor:\n            self.extra_host_mem_release_queues.setdefault(entry.name, Queue())\n        if self.enable_storage and self.storage_backend is not None:\n            self.storage_backend.register_mem_host_pool_v2(entry.host_pool, entry.name)\n\n    @staticmethod\n    def parse_storage_backend_extra_config(\n        storage_backend_extra_config: Optional[str],\n    ) -> tuple[dict, int, float, float, bool]:\n        extra_config = {}\n        if storage_backend_extra_config:\n            if storage_backend_extra_config.startswith(\"@\"):\n                path = storage_backend_extra_config[1:]\n                ext = os.path.splitext(path)[1].lower()\n                with open(path, \"rb\" if ext == \".toml\" else \"r\") as f:\n                    if ext == \".json\":\n                        extra_config = json.load(f)","sourceCodeStart":155,"sourceCodeEnd":191,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/mem_cache/hybrid_cache/hybrid_cache_controller.py#L155-L191","documentation":"HybridCacheController.register_host_pool_entry registers an extra host memory pool ('sidecar') for dynamic HiCache, but this only works when the controller's host memory is organized as a HostPoolGroup (multiple named pools). If mem_pool_host is a single flat pool (not a HostPoolGroup instance), adding named entries is meaningless and a TypeError is raised.","triggerScenarios":"Calling register_host_pool_entry / register_sidecar_pool on a HybridCacheController that was constructed with a plain host memory pool instead of HostPoolGroup — i.e. dynamic sidecar pools were not enabled at construction time.","commonSituations":"Programmatically registering sidecar host pools without enabling the HostPoolGroup configuration in server args / controller init; version changes where the default host pool type switched; custom setups constructing HybridCacheController manually with a single HiKVPool.","solutions":["Initialize the controller with a HostPoolGroup as mem_pool_host (enable the dynamic sidecar / host pool group option in server args) before registering sidecar entries","Guard the call: check isinstance(controller.mem_pool_host, HostPoolGroup) and skip/log otherwise","If you don't need dynamic sidecars, remove the register_sidecar_pool call"],"exampleFix":"# before\ncontroller.register_host_pool_entry(entry)  # mem_pool_host is a flat pool\n\n# after\nfrom sglang.srt.mem_cache.hybrid_allocator import HostPoolGroup\nassert isinstance(controller.mem_pool_host, HostPoolGroup), \"enable HostPoolGroup before adding sidecars\"\ncontroller.register_host_pool_entry(entry)","handlingStrategy":"type-guard","validationCode":"from sglang.srt.mem_cache.hybrid_allocator import HostPoolGroup\nif not isinstance(controller.mem_pool_host, HostPoolGroup):\n    raise RuntimeError(\"construct controller with HostPoolGroup before registering sidecars\")","typeGuard":"def can_register_sidecar(controller) -> bool:\n    return isinstance(getattr(controller, \"mem_pool_host\", None), HostPoolGroup)","tryCatchPattern":"try:\n    controller.register_host_pool_entry(entry)\nexcept TypeError as e:\n    if \"HostPoolGroup\" in str(e):\n        logger.warning(\"sidecar registration skipped: HostPoolGroup not enabled\")\n    else:\n        raise","preventionTips":["Enable HostPoolGroup in server args when dynamic sidecar pools are planned","Assert pool type in test harnesses that register sidecar pools programmatically"],"tags":["hicache","hybrid-cache","sidecar","type-error"],"backgroundTag":"wrong-pool-type-registration","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}