vllm-project/vllm · error · ValueError

kv_transfer_config must be set to create a connector

Error message

kv_transfer_config must be set to create a connector

What it means

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.

Source

Thrown at vllm/distributed/kv_transfer/kv_connector/factory.py:51

        if name in cls._registry:
            raise ValueError(f"Connector '{name}' is already registered.")

        def loader() -> type[KVConnectorBase]:
            module = importlib.import_module(module_path)
            return getattr(module, class_name)

        cls._registry[name] = loader

    @classmethod
    def create_connector(
        cls,
        config: "VllmConfig",
        role: KVConnectorRole,
        kv_cache_config: "KVCacheConfig",
    ) -> KVConnectorBase:
        kv_transfer_config = config.kv_transfer_config
        if kv_transfer_config is None:
            raise ValueError("kv_transfer_config must be set to create a connector")
        connector_cls = cls.get_connector_class(kv_transfer_config)

        # check if the connector supports HMA
        hma_enabled = not config.scheduler_config.disable_hybrid_kv_cache_manager
        if hma_enabled and not cls.supports_hma_config(kv_transfer_config):
            raise ValueError(
                f"Connector {connector_cls.__name__} does not support HMA but "
                f"HMA is enabled. Please set `--disable-hybrid-kv-cache-manager`."
            )

        logger.info(
            "Creating v1 connector with name: %s and engine_id: %s",
            connector_cls.__name__,
            kv_transfer_config.engine_id,
        )
        # NOTE(Kuntai): v1 connector is explicitly separated into two roles.
        # Scheduler connector:
        # - Co-locate with scheduler process

View on GitHub (pinned to c794754062)

Solutions

  1. Start vLLM with a KV transfer config, e.g. --kv-transfer-config '{"kv_connector":"SharedStorageConnector","kv_role":"kv_producer",...}'
  2. If constructing VllmConfig in Python, set vllm_config.kv_transfer_config = KVTransferConfig(...) before calling create_connector
  3. If connectors are not intended for this run, remove the code path that invokes create_connector

Example fix

# before
factory.create_connector(vllm_config, role, kv_cache_config)  # kv_transfer_config is None

# after
from vllm.config import KVTransferConfig
vllm_config.kv_transfer_config = KVTransferConfig(
    kv_connector="NixlConnector", kv_role="kv_producer"
)
factory.create_connector(vllm_config, role, kv_cache_config)
Defensive patterns

Strategy: validation

Validate before calling

if vllm_config.kv_transfer_config is None:
    raise SystemExit("Start vLLM with --kv-transfer-config before creating a connector")
connector = KVConnectorFactory.create_connector(vllm_config, role, kv_cache_config)

Type guard

def has_kv_transfer_config(cfg) -> bool:
    return getattr(cfg, "kv_transfer_config", None) is not None

Try / catch

try:
    connector = KVConnectorFactory.create_connector(cfg, role, kv_cache_config)
except ValueError as e:
    if 'kv_transfer_config must be set' in str(e):
        cfg.kv_transfer_config = KVTransferConfig(kv_connector="...", kv_role="...")
        connector = KVConnectorFactory.create_connector(cfg, role, kv_cache_config)
    else:
        raise

Prevention

When it happens

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

Common situations: 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.

Related errors

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