vllm-project/vllm · error · ValueError

Connector {connector_cls.__name__} uses deprecated 2-argumen

Error message

Connector {connector_cls.__name__} uses deprecated 2-argument constructor signature. External v1 KV connectors must accept kv_cache_config as the third constructor argument and pass it to super().__init__().

What it means

An external v1 connector class resolved via kv_connector_module_path does not accept a kv_cache_config keyword argument (checked with supports_kw). Older v1 connectors used a 2-argument constructor (vllm_config, role); the current factory contract requires the 3-argument signature including kv_cache_config, which must be forwarded to super().__init__().

Source

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

        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 "
                    "constructor argument and pass it to super().__init__()."
                )
                logger.error(msg)
                raise ValueError(msg)
        elif connector_name in cls._registry:
            connector_cls = cls._registry[connector_name]()
        else:
            raise ValueError(f"Unsupported connector type: {connector_name}")
        return connector_cls

    @classmethod
    def supports_hma_config(cls, kv_transfer_config: "KVTransferConfig") -> bool:
        """Return whether this KV transfer config supports HMA.

        MultiConnector is a special case: the wrapper class implements
        SupportsHMA, but effective support depends on every configured child.
        """
        connector_cls = cls.get_connector_class(kv_transfer_config)
        if kv_transfer_config.kv_connector != "MultiConnector":
            return supports_hma(connector_cls)

        from vllm.distributed.kv_transfer.kv_connector.v1.multi_connector import (

View on GitHub (pinned to c794754062)

Solutions

1. Update the external connector's __init__ to accept kv_cache_config as the third argument and pass it to super().__init__() (the base KVConnectorBase_V1 signature shows the exact shape)
2. Upgrade the external connector package to a version compatible with your vLLM release
3. As a stopgap, pin vLLM to the version the connector was written for

Example fix

# before
class MyConnector(KVConnectorBase_V1):
    def __init__(self, vllm_config, role):
        super().__init__(vllm_config=vllm_config, role=role)

# after
class MyConnector(KVConnectorBase_V1):
    def __init__(self, vllm_config, role, kv_cache_config):
        super().__init__(
            vllm_config=vllm_config, role=role, kv_cache_config=kv_cache_config
        )

from vllm.utils import supports_kw
cls = getattr(importlib.import_module(cfg.kv_connector_module_path), cfg.kv_connector)
if not supports_kw(cls, "kv_cache_config"):
    raise SystemExit("External connector uses deprecated 2-arg constructor; upgrade it")

def connector_accepts_kv_cache_config(cls) -> bool:
    return supports_kw(cls, "kv_cache_config")

When it happens

Trigger: Using an external connector written against the pre-kv_cache_config API: its __init__(self, vllm_config, role) fails the supports_kw(connector_cls, 'kv_cache_config') probe in get_connector_class.

Common situations: vLLM upgrade introduced the third constructor argument and the third-party connector has not caught up; copying an old example connector implementation.

Related errors

• Class {connector_name} not found in {connector_module_path}
• HTTP request failed: {0}
• JSON error: {0}
• Tokenizer error: {0}
• tokenize endpoint unavailable: {0}

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