vllm-project/vllm · error · ValueError

Unsupported connector type: {connector_name}

Error message

Unsupported connector type: {connector_name}

What it means

get_connector_class resolved neither an external module path (kv_connector_module_path falsy) nor a registry entry for kv_connector, so the name is unsupported. This is the fallback branch after the registry check fails — the name is neither built-in nor externally locatable.

Source

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

                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 (
            MultiConnector,
        )

        return MultiConnector.all_children_support_hma(kv_transfer_config)

View on GitHub (pinned to c794754062)

Solutions

1. For external connectors, set kv_connector_module_path to the module containing the class
2. For built-in connectors, check the exact registered name for your vLLM version
3. Upgrade/downgrade vLLM to the version where this connector name is registered

Example fix

# before
KVTransferConfig(kv_connector="LMCacheConnectorV1")  # not in registry

# after
KVTransferConfig(
    kv_connector="LMCacheConnectorV1",
    kv_connector_module_path="lmcache.integration.vllm.v1_connector",
)

name = cfg.kv_connector
known = cfg.kv_connector_module_path is not None or name in KVConnectorFactory._registry
if not known:
    raise SystemExit(f"Unsupported connector type: {name}; set kv_connector_module_path")

def connector_resolvable(cfg) -> bool:
    return (
        bool(cfg.kv_connector_module_path)
        or cfg.kv_connector in KVConnectorFactory._registry
    )

When it happens

Trigger: kv_connector set to a name that is not in the factory registry and kv_connector_module_path is None/empty. Common with names of connectors that exist in other vLLM versions or in external repos without the module path configured.

Common situations: Version skew: connector name valid in newer/older vLLM but not in the running one; third-party connector used without kv_connector_module_path; typo in the connector name.

Related errors

• Connector '{connector_name}' is not registered.
• {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/4edf4f594f392204. Report an issue: GitHub.