vllm-project/vllm · error · ValueError

Unknown KVConnectorRole: {self.role}

Error message

Unknown KVConnectorRole: {self.role}

What it means

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.

Source

Thrown at vllm/distributed/kv_transfer/kv_connector/v1/lmcache_mp_connector.py:522

        if self.role == KVConnectorRole.SCHEDULER:
            self.scheduler_adapter = create_scheduler_adapter(
                server_url,
                zmq_context,
                vllm_config,
                mq_timeout,
                heartbeat_interval,
            )
            self.request_trackers: dict[str, LMCacheMPRequestTracker] = {}
        elif self.role == KVConnectorRole.WORKER:
            self.worker_adapter = create_worker_adapter(
                server_url,
                zmq_context,
                vllm_config,
                mq_timeout,
                heartbeat_interval,
            )
        else:
            raise ValueError(f"Unknown KVConnectorRole: {self.role}")

        self.vllm_block_size = vllm_config.cache_config.block_size

    @property
    def role(self) -> KVConnectorRole:
        return self._role

    # ==============================
    # Worker-side methods
    # ==============================

    def _get_connector_metadata(self) -> KVConnectorMetadata:
        """Get the connector metadata.

        This function should only be called inside the connector.

        Returns:
            ConnectorMetadata: the connector metadata.

View on GitHub (pinned to c794754062)

Solutions

1. Pin vllm and lmcache to a compatible version pair per LMCache's compatibility matrix.
2. In tests, pass real KVConnectorRole.ENGINE_PARALLEL or KVConnectorRole.WORKER values, not strings or mocks.
3. If you maintain a fork adding roles, extend the connector's role dispatch to handle them.

Example fix

# before
connector = LMCacheMPConnector(role="scheduler", ...)
# after
from vllm.distributed.kv_transfer.kv_connector.utils import KVConnectorRole
connector = LMCacheMPConnector(role=KVConnectorRole.ENGINE_PARALLEL, ...)

from vllm.distributed.kv_transfer.kv_connector.utils import KVConnectorRole
def is_known_role(role) -> bool:
    return role in (KVConnectorRole.ENGINE_PARALLEL, KVConnectorRole.WORKER)

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.

When it happens

Trigger: 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.

Common situations: vLLM upgraded to a version that extends KVConnectorRole while lmcache lags; unit tests constructing the connector with a stubbed role object.

Related errors

• Either vllm_config must be provided, or all of model_config,
• Unsupported new_block_ids type {type(new_block_ids)}: should
• MLA only works with naive serde mode..
• layerwise MLA connector is not supported yet
• LMCacheMPConnector only works without hybrid kv cache manage

AI-assisted analysis of vllm-project/vllm@c794754062 (2026-08-14). Data as JSON: /api/errors/a50748753b110c24. Report an issue: GitHub.