vllm-project/vllm · error · ValueError

kv_transfer_config must be set for KVConnectorBase_V1

Error message

kv_transfer_config must be set for KVConnectorBase_V1

What it means

KVConnectorBase_V1.__init__ stores vllm_config.kv_transfer_config and raises if it is None. Any v1 connector (built-in or custom) instantiated without a KVTransferConfig in the VllmConfig hits this in the base-class constructor, before subclass init logic runs.

Source

Thrown at vllm/distributed/kv_transfer/kv_connector/v1/base.py:220

        """
        return self._kv_transfer_config.is_kv_producer

    def __init__(
        self,
        vllm_config: "VllmConfig",
        role: KVConnectorRole,
        kv_cache_config: "KVCacheConfig",
    ):
        logger.warning(
            "Initializing KVConnectorBase_V1. This API is experimental and "
            "subject to change in the future as we iterate the design."
        )
        self._connector_metadata: KVConnectorMetadata | None = None
        self._vllm_config = vllm_config
        if vllm_config.kv_transfer_config is not None:
            self._kv_transfer_config = vllm_config.kv_transfer_config
        else:
            raise ValueError("kv_transfer_config must be set for KVConnectorBase_V1")
        self._kv_cache_config = kv_cache_config
        self._role = role

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

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

    def bind_connector_metadata(self, connector_metadata: KVConnectorMetadata) -> None:
        """Set the connector metadata from the scheduler.

        This function should be called by the model runner every time
        before the model execution. The metadata will be used for runtime
        KV cache loading and saving.

View on GitHub (pinned to c794754062)

Solutions

1. Populate kv_transfer_config in the VllmConfig before constructing the connector (e.g. --kv-transfer-config on the CLI)
2. In unit tests, build the config with VllmConfig(..., kv_transfer_config=KVTransferConfig(kv_connector=..., kv_role=...))

Example fix

# before
connector = MyConnector(vllm_config, role, kv_cache_config)  # no kv_transfer_config

# after
vllm_config.kv_transfer_config = KVTransferConfig(
    kv_connector="MyConnector", kv_role="kv_producer"
)
connector = MyConnector(vllm_config, role, kv_cache_config)

assert vllm_config.kv_transfer_config is not None, (
    "KVConnectorBase_V1 requires kv_transfer_config"
)

When it happens

Trigger: Instantiating any subclass of KVConnectorBase_V1 (directly or via the factory) with a VllmConfig where kv_transfer_config is None.

Common situations: Same root cause as the factory-level check: engine started without --kv-transfer-config; unit tests constructing connectors with a bare VllmConfig; custom connectors initialized in a worker without the config populated.

Related errors

• --use-replayssm is incompatible with KV connectors (P/D disa
• kv_transfer_config must be set to create a connector
• Connector {connector_cls.__name__} does not support HMA but
• Connector '{connector_name}' is not registered.
• Connector name is not set in KVTransferConfig

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