{"record":{"id":"a50748753b110c24","repo":"vllm-project/vllm","slug":"unknown-kvconnectorrole-self-role","errorCode":null,"errorMessage":"Unknown KVConnectorRole: {self.role}","messagePattern":"Unknown KVConnectorRole: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/distributed/kv_transfer/kv_connector/v1/lmcache_mp_connector.py","lineNumber":522,"sourceCode":"        if self.role == KVConnectorRole.SCHEDULER:\n            self.scheduler_adapter = create_scheduler_adapter(\n                server_url,\n                zmq_context,\n                vllm_config,\n                mq_timeout,\n                heartbeat_interval,\n            )\n            self.request_trackers: dict[str, LMCacheMPRequestTracker] = {}\n        elif self.role == KVConnectorRole.WORKER:\n            self.worker_adapter = create_worker_adapter(\n                server_url,\n                zmq_context,\n                vllm_config,\n                mq_timeout,\n                heartbeat_interval,\n            )\n        else:\n            raise ValueError(f\"Unknown KVConnectorRole: {self.role}\")\n\n        self.vllm_block_size = vllm_config.cache_config.block_size\n\n    @property\n    def role(self) -> KVConnectorRole:\n        return self._role\n\n    # ==============================\n    # Worker-side methods\n    # ==============================\n\n    def _get_connector_metadata(self) -> KVConnectorMetadata:\n        \"\"\"Get the connector metadata.\n\n        This function should only be called inside the connector.\n\n        Returns:\n            ConnectorMetadata: the connector metadata.","sourceCodeStart":504,"sourceCodeEnd":540,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/distributed/kv_transfer/kv_connector/v1/lmcache_mp_connector.py#L504-L540","documentation":"ValueError from LMCacheMPConnector.__init__ when self.role is neither KVConnectorRole.ENGINE_PARALLEL nor KVConnectorRole.WORKER. The connector builds completely different adapters per role (scheduler-side vs worker-side), so an unknown role cannot proceed. KVConnectorRole is a vLLM enum; an unknown value means the enum grew (new role added) or an invalid value was injected by custom orchestration code.","triggerScenarios":"Instantiating LMCacheMPConnector with a role from a newer vLLM (e.g. a role added for other connector architectures) that predates LMCacheMP support; passing a raw string or mock instead of the enum in tests; fork of vLLM adding a custom role.","commonSituations":"vLLM upgraded to a version that extends KVConnectorRole while lmcache lags; unit tests constructing the connector with a stubbed role object.","solutions":["Pin vllm and lmcache to a compatible version pair per LMCache's compatibility matrix.","In tests, pass real KVConnectorRole.ENGINE_PARALLEL or KVConnectorRole.WORKER values, not strings or mocks.","If you maintain a fork adding roles, extend the connector's role dispatch to handle them."],"exampleFix":"# before\nconnector = LMCacheMPConnector(role=\"scheduler\", ...)\n# after\nfrom vllm.distributed.kv_transfer.kv_connector.utils import KVConnectorRole\nconnector = LMCacheMPConnector(role=KVConnectorRole.ENGINE_PARALLEL, ...)","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"from vllm.distributed.kv_transfer.kv_connector.utils import KVConnectorRole\ndef is_known_role(role) -> bool:\n    return role in (KVConnectorRole.ENGINE_PARALLEL, KVConnectorRole.WORKER)","tryCatchPattern":"Catch ValueError at connector construction; fail fast with the role value in the message — an unknown role is a version/contract problem to fix, not to handle at runtime.","preventionTips":["Pass real KVConnectorRole enum values, never strings or mocks","Pin vllm/lmcache versions together"],"tags":["lmcache","enum","version-mismatch","config","kv-transfer"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}