{"record":{"id":"ce9397fa5e0e4c28","repo":"sgl-project/sglang","slug":"unregistered-umbp-hybrid-pool","errorCode":null,"errorMessage":"Unregistered UMBP hybrid pool: {}","messagePattern":"Unregistered UMBP hybrid pool: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/mem_cache/storage/umbp/umbp_store.py","lineNumber":1245,"sourceCode":"    # logical KV anchor that owns only page indices. The controller registers\n    # each real pool through register_mem_host_pool_v2() and drives storage\n    # via these _v2 methods, one PoolTransfer per pool. This mirrors the proven\n    # MooncakeStore / HiCacheHF3FS design, specialized for UMBP's page_first,\n    # single-object-per-page layout (each page -> exactly one storage object).\n    # ------------------------------------------------------------------\n    def _get_hybrid_page_component_keys(self, page_keys, transfer: PoolTransfer):\n        \"\"\"Map per-page logical keys to per-object storage keys for a side pool.\n\n        For UMBP every registered side pool is page_first and stores one object\n        per page (MLA: a single K object; MHA: a K and a V object), so the\n        component-key count is an exact multiple of the page count. The pool\n        name is embedded in the suffix so pages that share a hash across pools\n        never collide.\n        \"\"\"\n        pool_name = transfer.name\n        host_pool = self.registered_pools.get(pool_name)\n        if host_pool is None:\n            raise ValueError(f\"Unregistered UMBP hybrid pool: {pool_name}\")\n\n        if self.is_mla_backend:\n            # Single compressed object per page.\n            suffixes = [f\"_{self.mla_suffix}_{pool_name}\"]\n        elif getattr(host_pool, \"v_buffer\", None) is not None:\n            # Ordinary MHA side pool mirrors a K/V pool.\n            suffixes = [\n                f\"_{self.mha_suffix}_{pool_name}_k\",\n                f\"_{self.mha_suffix}_{pool_name}_v\",\n            ]\n        else:\n            suffixes = [f\"_{self.mha_suffix}_{pool_name}\"]\n\n        key_multiplier = len(suffixes)\n        component_keys = [\n            f\"{page_key}{suffix}\" for page_key in page_keys for suffix in suffixes\n        ]\n        return component_keys, key_multiplier","sourceCodeStart":1227,"sourceCodeEnd":1263,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/mem_cache/storage/umbp/umbp_store.py#L1227-L1263","documentation":"During hybrid (MLA/MHA) page key composition, the pool name on a PoolTransfer was not found in registered_pools, so per-page suffix keys cannot be built. Each transfer must reference a pool registered with the UMBP store.","triggerScenarios":"Calling batch_exists_v2 or _batch_io_v2 with a PoolTransfer whose .name doesn't match any registered host pool (typo, unregistered pool, or registration skipped).","commonSituations":"Adding a new hybrid pool but forgetting to register it with the UMBP store; renaming pools between components; race where transfer is built before registration completes.","solutions":["Ensure every pool referenced by transfers is registered (registered_pools) before issuing batch I/O","Check for name typos/mismatch between the pool registration and the PoolTransfer construction","Register pools during model runner init before scheduler-driven I/O starts"],"exampleFix":"// before\ntransfer = PoolTransfer(name='kv_pool_mha', ...)\nstore.batch_get_v2([transfer])\n// after\nstore.registered_pools['kv_pool_mha'] = host_pool  # ensure registered first\ntransfer = PoolTransfer(name='kv_pool_mha', ...)  # must match exactly\nstore.batch_get_v2([transfer])","handlingStrategy":"validation","validationCode":"assert transfer.name in store.registered_pools, f\"pool {transfer.name!r} not registered\"","typeGuard":"def transfer_pool_registered(store, t) -> bool:\n    return t.name in store.registered_pools","tryCatchPattern":null,"preventionTips":["Register all hybrid pools before issuing batch I/O","Add init-time assertions enumerating required pool names"],"tags":["umbp","hybrid-pool","registration"],"backgroundTag":"unregistered-resource","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}