{"record":{"id":"5fbe55c738366c4c","repo":"vllm-project/vllm","slug":"kv-transfer-config-must-be-set-for-kvconnectorbase","errorCode":null,"errorMessage":"kv_transfer_config must be set for KVConnectorBase_V1","messagePattern":"kv_transfer_config must be set for KVConnectorBase_V1","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/distributed/kv_transfer/kv_connector/v1/base.py","lineNumber":220,"sourceCode":"        \"\"\"\n        return self._kv_transfer_config.is_kv_producer\n\n    def __init__(\n        self,\n        vllm_config: \"VllmConfig\",\n        role: KVConnectorRole,\n        kv_cache_config: \"KVCacheConfig\",\n    ):\n        logger.warning(\n            \"Initializing KVConnectorBase_V1. This API is experimental and \"\n            \"subject to change in the future as we iterate the design.\"\n        )\n        self._connector_metadata: KVConnectorMetadata | None = None\n        self._vllm_config = vllm_config\n        if vllm_config.kv_transfer_config is not None:\n            self._kv_transfer_config = vllm_config.kv_transfer_config\n        else:\n            raise ValueError(\"kv_transfer_config must be set for KVConnectorBase_V1\")\n        self._kv_cache_config = kv_cache_config\n        self._role = role\n\n    @property\n    def role(self) -> KVConnectorRole:\n        return self._role\n\n    # ==============================\n    # Worker-side methods\n    # ==============================\n\n    def bind_connector_metadata(self, connector_metadata: KVConnectorMetadata) -> None:\n        \"\"\"Set the connector metadata from the scheduler.\n\n        This function should be called by the model runner every time\n        before the model execution. The metadata will be used for runtime\n        KV cache loading and saving.\n","sourceCodeStart":202,"sourceCodeEnd":238,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/distributed/kv_transfer/kv_connector/v1/base.py#L202-L238","documentation":"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.","triggerScenarios":"Instantiating any subclass of KVConnectorBase_V1 (directly or via the factory) with a VllmConfig where kv_transfer_config is None.","commonSituations":"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.","solutions":["Populate kv_transfer_config in the VllmConfig before constructing the connector (e.g. --kv-transfer-config on the CLI)","In unit tests, build the config with VllmConfig(..., kv_transfer_config=KVTransferConfig(kv_connector=..., kv_role=...))"],"exampleFix":"# before\nconnector = MyConnector(vllm_config, role, kv_cache_config)  # no kv_transfer_config\n\n# after\nvllm_config.kv_transfer_config = KVTransferConfig(\n    kv_connector=\"MyConnector\", kv_role=\"kv_producer\"\n)\nconnector = MyConnector(vllm_config, role, kv_cache_config)","handlingStrategy":"validation","validationCode":"assert vllm_config.kv_transfer_config is not None, (\n    \"KVConnectorBase_V1 requires kv_transfer_config\"\n)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Build VllmConfig through one factory helper that always sets kv_transfer_config","In unit tests, reuse a fixture that pre-populates kv_transfer_config"],"tags":["kv-transfer","config","base-class","vllm"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}