{"record":{"id":"9fd9bd3a85ec70e8","repo":"vllm-project/vllm","slug":"connector-connector-cls-name-uses-deprecated","errorCode":null,"errorMessage":"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__().","messagePattern":"Connector (.+?) 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__\\(\\)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/distributed/kv_transfer/kv_connector/factory.py","lineNumber":123,"sourceCode":"        if connector_module_path:\n            # External module path takes priority over internal registry.\n            connector_module = importlib.import_module(connector_module_path)\n            try:\n                connector_cls = getattr(connector_module, connector_name)\n            except AttributeError as e:\n                raise AttributeError(\n                    f\"Class {connector_name} not found in {connector_module_path}\"\n                ) from e\n            connector_cls = cast(type[KVConnectorBaseType], connector_cls)\n            if not supports_kw(connector_cls, \"kv_cache_config\"):\n                msg = (\n                    f\"Connector {connector_cls.__name__} uses deprecated \"\n                    \"2-argument constructor signature. External v1 KV \"\n                    \"connectors must accept kv_cache_config as the third \"\n                    \"constructor argument and pass it to super().__init__().\"\n                )\n                logger.error(msg)\n                raise ValueError(msg)\n        elif connector_name in cls._registry:\n            connector_cls = cls._registry[connector_name]()\n        else:\n            raise ValueError(f\"Unsupported connector type: {connector_name}\")\n        return connector_cls\n\n    @classmethod\n    def supports_hma_config(cls, kv_transfer_config: \"KVTransferConfig\") -> bool:\n        \"\"\"Return whether this KV transfer config supports HMA.\n\n        MultiConnector is a special case: the wrapper class implements\n        SupportsHMA, but effective support depends on every configured child.\n        \"\"\"\n        connector_cls = cls.get_connector_class(kv_transfer_config)\n        if kv_transfer_config.kv_connector != \"MultiConnector\":\n            return supports_hma(connector_cls)\n\n        from vllm.distributed.kv_transfer.kv_connector.v1.multi_connector import (","sourceCodeStart":105,"sourceCodeEnd":141,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/distributed/kv_transfer/kv_connector/factory.py#L105-L141","documentation":"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__().","triggerScenarios":"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.","commonSituations":"vLLM upgrade introduced the third constructor argument and the third-party connector has not caught up; copying an old example connector implementation.","solutions":["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)","Upgrade the external connector package to a version compatible with your vLLM release","As a stopgap, pin vLLM to the version the connector was written for"],"exampleFix":"# before\nclass MyConnector(KVConnectorBase_V1):\n    def __init__(self, vllm_config, role):\n        super().__init__(vllm_config=vllm_config, role=role)\n\n# after\nclass MyConnector(KVConnectorBase_V1):\n    def __init__(self, vllm_config, role, kv_cache_config):\n        super().__init__(\n            vllm_config=vllm_config, role=role, kv_cache_config=kv_cache_config\n        )","handlingStrategy":"validation","validationCode":"from vllm.utils import supports_kw\ncls = getattr(importlib.import_module(cfg.kv_connector_module_path), cfg.kv_connector)\nif not supports_kw(cls, \"kv_cache_config\"):\n    raise SystemExit(\"External connector uses deprecated 2-arg constructor; upgrade it\")","typeGuard":"def connector_accepts_kv_cache_config(cls) -> bool:\n    return supports_kw(cls, \"kv_cache_config\")","tryCatchPattern":null,"preventionTips":["Keep external connectors in lockstep with the vLLM constructor contract","Add a construction unit test to external connector packages"],"tags":["kv-transfer","api-change","external-connector","vllm"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}