{"record":{"id":"2ab7c25e3489e33e","repo":"vllm-project/vllm","slug":"connector-connector-name-is-not-registered","errorCode":null,"errorMessage":"Connector '{connector_name}' is not registered.","messagePattern":"Connector '(.+?)' is not registered\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/distributed/kv_transfer/kv_connector/factory.py","lineNumber":92,"sourceCode":"        # We build separately to enforce strict separation\n        return connector_cls(config, role, kv_cache_config)\n\n    @classmethod\n    def get_connector_class_by_name(\n        cls, connector_name: str\n    ) -> type[KVConnectorBaseType]:\n        \"\"\"Get a registered connector class by name.\n\n        Raises ValueError if the connector is not registered.\n\n        Args:\n            connector_name: Name of the registered connector.\n\n        Returns:\n            The connector class.\n        \"\"\"\n        if connector_name not in cls._registry:\n            raise ValueError(f\"Connector '{connector_name}' is not registered.\")\n        return cls._registry[connector_name]()\n\n    @classmethod\n    def get_connector_class(\n        cls, kv_transfer_config: \"KVTransferConfig\"\n    ) -> type[KVConnectorBaseType]:\n        connector_name = kv_transfer_config.kv_connector\n        if connector_name is None:\n            raise ValueError(\"Connector name is not set in KVTransferConfig\")\n        connector_module_path = kv_transfer_config.kv_connector_module_path\n        if connector_module_path is not None and not connector_module_path:\n            raise ValueError(\"kv_connector_module_path cannot be an empty string.\")\n        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:","sourceCodeStart":74,"sourceCodeEnd":110,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/distributed/kv_transfer/kv_connector/factory.py#L74-L110","documentation":"A lookup in the factory's internal connector registry failed: the name given is not among the connectors registered via register_connector. The factory keeps a name->loader registry for built-in v1 connectors; unknown names are rejected before instantiation.","triggerScenarios":"Calling the registry getter with a name that is not registered — e.g. KVConnectorFactory.get_connector_class on a KVTransferConfig whose kv_connector is misspelled ('NvidiaKDAGPUConnectorV2', wrong casing) or is an external connector loaded without kv_connector_module_path.","commonSituations":"Typos in the kv_connector name; referencing a connector removed/renamed in a newer vLLM; expecting a third-party connector to be in the built-in registry.","solutions":["Check exact spelling/case of kv_connector against the registry (e.g. 'NixlConnector', 'SharedStorageConnector')","For external connectors, set kv_connector_module_path in KVTransferConfig so the import path is used instead of the registry","If the connector should be built-in, verify it is registered via KVConnectorFactory.register_connector in the version you run"],"exampleFix":"# before\nKVTransferConfig(kv_connector=\"NixlConnectorV1\")  # not registered\n\n# after (built-in)\nKVTransferConfig(kv_connector=\"NixlConnector\")\n# after (external)\nKVTransferConfig(\n    kv_connector=\"MyConnector\",\n    kv_connector_module_path=\"my_pkg.connectors\",\n)","handlingStrategy":"validation","validationCode":"name = kv_transfer_config.kv_connector\nif kv_transfer_config.kv_connector_module_path is None and name not in KVConnectorFactory._registry:\n    raise SystemExit(f\"Unknown connector {name!r}; set kv_connector_module_path or fix the name\")","typeGuard":"def is_registered_connector(name: str) -> bool:\n    return name in KVConnectorFactory._registry","tryCatchPattern":"try:\n    cls = KVConnectorFactory.get_connector_class(kv_transfer_config)\nexcept ValueError as e:\n    raise SystemExit(f\"Bad kv_connector config: {e}\") from e","preventionTips":["Validate connector names against the registry at config-load time","Add a startup smoke test that resolves the connector class before serving","Prefer kv_connector_module_path for anything not built into vLLM"],"tags":["kv-transfer","registry","config","vllm"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}