vllm-project/vllm · error · ValueError

Connector '{connector_name}' is not registered.

Error message

Connector '{connector_name}' is not registered.

What it means

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.

Source

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

        # We build separately to enforce strict separation
        return connector_cls(config, role, kv_cache_config)

    @classmethod
    def get_connector_class_by_name(
        cls, connector_name: str
    ) -> type[KVConnectorBaseType]:
        """Get a registered connector class by name.

        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:

View on GitHub (pinned to c794754062)

Solutions

1. Check exact spelling/case of kv_connector against the registry (e.g. 'NixlConnector', 'SharedStorageConnector')
2. For external connectors, set kv_connector_module_path in KVTransferConfig so the import path is used instead of the registry
3. If the connector should be built-in, verify it is registered via KVConnectorFactory.register_connector in the version you run

Example fix

# before
KVTransferConfig(kv_connector="NixlConnectorV1")  # not registered

# after (built-in)
KVTransferConfig(kv_connector="NixlConnector")
# after (external)
KVTransferConfig(
    kv_connector="MyConnector",
    kv_connector_module_path="my_pkg.connectors",
)

name = kv_transfer_config.kv_connector
if kv_transfer_config.kv_connector_module_path is None and name not in KVConnectorFactory._registry:
    raise SystemExit(f"Unknown connector {name!r}; set kv_connector_module_path or fix the name")

def is_registered_connector(name: str) -> bool:
    return name in KVConnectorFactory._registry

try:
    cls = KVConnectorFactory.get_connector_class(kv_transfer_config)
except ValueError as e:
    raise SystemExit(f"Bad kv_connector config: {e}") from e

When it happens

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

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

Related errors

• Unsupported connector type: {connector_name}
• {kind} parsing is disabled by frontend configuration
• --use-replayssm is incompatible with KV connectors (P/D disa
• Unsupported sleep-mode backend '{name}'. Registered backends
• kv_transfer_config must be set to create a connector

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