vllm-project/vllm · error · ValueError

Connector name is not set in KVTransferConfig

Error message

Connector name is not set in KVTransferConfig

What it means

KVConnectorFactory.get_connector_class reads kv_transfer_config.kv_connector and found None. Without a connector name the factory can neither look up the registry nor import from an external module, so it raises immediately.

Source

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

        Raises ValueError if the connector is not registered.

        Args:
            connector_name: Name of the registered connector.

        Returns:
            The connector class.
        """
        if connector_name not in cls._registry:
            raise ValueError(f"Connector '{connector_name}' is not registered.")
        return cls._registry[connector_name]()

    @classmethod
    def get_connector_class(
        cls, kv_transfer_config: "KVTransferConfig"
    ) -> type[KVConnectorBaseType]:
        connector_name = kv_transfer_config.kv_connector
        if connector_name is None:
            raise ValueError("Connector name is not set in KVTransferConfig")
        connector_module_path = kv_transfer_config.kv_connector_module_path
        if connector_module_path is not None and not connector_module_path:
            raise ValueError("kv_connector_module_path cannot be an empty string.")
        if connector_module_path:
            # External module path takes priority over internal registry.
            connector_module = importlib.import_module(connector_module_path)
            try:
                connector_cls = getattr(connector_module, connector_name)
            except AttributeError as e:
                raise AttributeError(
                    f"Class {connector_name} not found in {connector_module_path}"
                ) from e
            connector_cls = cast(type[KVConnectorBaseType], connector_cls)
            if not supports_kw(connector_cls, "kv_cache_config"):
                msg = (
                    f"Connector {connector_cls.__name__} uses deprecated "
                    "2-argument constructor signature. External v1 KV "
                    "connectors must accept kv_cache_config as the third "

View on GitHub (pinned to c794754062)

Solutions

1. Set kv_connector in the KVTransferConfig JSON/object, e.g. --kv-transfer-config '{"kv_connector":"NixlConnector","kv_role":"kv_producer"}'
2. If no connector is wanted, remove kv_transfer_config entirely instead of leaving kv_connector empty

Example fix

# before
KVTransferConfig(kv_role="kv_producer")

# after
KVTransferConfig(kv_connector="NixlConnector", kv_role="kv_producer")

if kv_transfer_config.kv_connector is None:
    raise SystemExit("KVTransferConfig.kv_connector must be set")

def has_connector_name(cfg) -> bool:
    return getattr(cfg, "kv_connector", None) is not None

When it happens

Trigger: Constructing KVTransferConfig with kv_connector unset (e.g. only kv_role or kv_role extra fields given), then any code that resolves the connector class (create_connector, supports_hma_config).

Common situations: Passing a partial JSON to --kv-transfer-config that sets kv_role but omits kv_connector; building KVTransferConfig programmatically with defaults.

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.
• kv_connector_module_path cannot be an empty string.

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