{"record":{"id":"8612d0fc3b3839a9","repo":"vllm-project/vllm","slug":"kv-transfer-config-must-be-set-to-create-a-connect","errorCode":null,"errorMessage":"kv_transfer_config must be set to create a connector","messagePattern":"kv_transfer_config must be set to create a connector","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/distributed/kv_transfer/kv_connector/factory.py","lineNumber":51,"sourceCode":"        if name in cls._registry:\n            raise ValueError(f\"Connector '{name}' is already registered.\")\n\n        def loader() -> type[KVConnectorBase]:\n            module = importlib.import_module(module_path)\n            return getattr(module, class_name)\n\n        cls._registry[name] = loader\n\n    @classmethod\n    def create_connector(\n        cls,\n        config: \"VllmConfig\",\n        role: KVConnectorRole,\n        kv_cache_config: \"KVCacheConfig\",\n    ) -> KVConnectorBase:\n        kv_transfer_config = config.kv_transfer_config\n        if kv_transfer_config is None:\n            raise ValueError(\"kv_transfer_config must be set to create a connector\")\n        connector_cls = cls.get_connector_class(kv_transfer_config)\n\n        # check if the connector supports HMA\n        hma_enabled = not config.scheduler_config.disable_hybrid_kv_cache_manager\n        if hma_enabled and not cls.supports_hma_config(kv_transfer_config):\n            raise ValueError(\n                f\"Connector {connector_cls.__name__} does not support HMA but \"\n                f\"HMA is enabled. Please set `--disable-hybrid-kv-cache-manager`.\"\n            )\n\n        logger.info(\n            \"Creating v1 connector with name: %s and engine_id: %s\",\n            connector_cls.__name__,\n            kv_transfer_config.engine_id,\n        )\n        # NOTE(Kuntai): v1 connector is explicitly separated into two roles.\n        # Scheduler connector:\n        # - Co-locate with scheduler process","sourceCodeStart":33,"sourceCodeEnd":69,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/distributed/kv_transfer/kv_connector/factory.py#L33-L69","documentation":"Raised by KVConnectorFactory.create_connector when the VllmConfig passed in has kv_transfer_config set to None. The factory cannot build a KV transfer connector without a KVTransferConfig, so it fails fast before any connector class is resolved. This is a configuration wiring error, not a connector bug.","triggerScenarios":"Calling KVConnectorFactory.create_connector(config, role, kv_cache_config) with a VllmConfig whose kv_transfer_config attribute is None — i.e. the engine was started without --kv-transfer-config / kv_transfer_config was never populated, but some code path (e.g. P/D disaggregation or a worker-side hook) still tries to instantiate a connector.","commonSituations":"Running PD-disaggregated serving without specifying --kv-transfer-config; programmatically building a VllmConfig and forgetting the kv_transfer_config field; a plugin/external script calling the factory directly on a default config.","solutions":["Start vLLM with a KV transfer config, e.g. --kv-transfer-config '{\"kv_connector\":\"SharedStorageConnector\",\"kv_role\":\"kv_producer\",...}'","If constructing VllmConfig in Python, set vllm_config.kv_transfer_config = KVTransferConfig(...) before calling create_connector","If connectors are not intended for this run, remove the code path that invokes create_connector"],"exampleFix":"# before\nfactory.create_connector(vllm_config, role, kv_cache_config)  # kv_transfer_config is None\n\n# after\nfrom vllm.config import KVTransferConfig\nvllm_config.kv_transfer_config = KVTransferConfig(\n    kv_connector=\"NixlConnector\", kv_role=\"kv_producer\"\n)\nfactory.create_connector(vllm_config, role, kv_cache_config)","handlingStrategy":"validation","validationCode":"if vllm_config.kv_transfer_config is None:\n    raise SystemExit(\"Start vLLM with --kv-transfer-config before creating a connector\")\nconnector = KVConnectorFactory.create_connector(vllm_config, role, kv_cache_config)","typeGuard":"def has_kv_transfer_config(cfg) -> bool:\n    return getattr(cfg, \"kv_transfer_config\", None) is not None","tryCatchPattern":"try:\n    connector = KVConnectorFactory.create_connector(cfg, role, kv_cache_config)\nexcept ValueError as e:\n    if 'kv_transfer_config must be set' in str(e):\n        cfg.kv_transfer_config = KVTransferConfig(kv_connector=\"...\", kv_role=\"...\")\n        connector = KVConnectorFactory.create_connector(cfg, role, kv_cache_config)\n    else:\n        raise","preventionTips":["Always pass --kv-transfer-config when running PD-disaggregated serving","Assert vllm_config.kv_transfer_config is not None in test fixtures that build connectors","Centralize KVTransferConfig construction in one helper so it is never omitted"],"tags":["kv-transfer","config","vllm","connector-factory"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}