vllm-project/vllm · error · ValueError

Connector '{name}' is already registered.

Error message

Connector '{name}' is already registered.

What it means

ECConnectorFactory.register_connector() keeps a class-level dict mapping connector names to lazy loaders. Registering the same name twice would silently replace the first implementation — a likely bug when modules get imported twice or two connectors share a name — so it raises ValueError on duplicates.

Source

Thrown at vllm/distributed/ec_transfer/ec_connector/factory.py:27

    ECConnectorBase,
    ECConnectorRole,
)
from vllm.logger import init_logger

if TYPE_CHECKING:
    from vllm.config import ECTransferConfig, VllmConfig

logger = init_logger(__name__)


class ECConnectorFactory:
    _registry: dict[str, Callable[[], type[ECConnectorBase]]] = {}

    @classmethod
    def register_connector(cls, name: str, module_path: str, class_name: str) -> None:
        """Register a connector with a lazy-loading module and class name."""
        if name in cls._registry:
            raise ValueError(f"Connector '{name}' is already registered.")

        def loader() -> type[ECConnectorBase]:
            module = importlib.import_module(module_path)
            return getattr(module, class_name)

        cls._registry[name] = loader

    @classmethod
    def create_connector(
        cls,
        config: "VllmConfig",
        role: ECConnectorRole,
    ) -> ECConnectorBase:
        ec_transfer_config = config.ec_transfer_config
        if ec_transfer_config is None:
            raise ValueError("ec_transfer_config must be set to create a connector")
        connector_cls = cls.get_connector_class(ec_transfer_config)
        logger.info(

View on GitHub (pinned to c794754062)

Solutions

1. Pick a unique connector name for your custom connector instead of overriding a built-in
2. If overriding is intended, pop the existing entry first: ECConnectorFactory._registry.pop(name, None) before register_connector
3. Avoid importlib.reload of modules containing registration calls, or guard registration with an `if name not in _registry` check

Example fix

# before
ECConnectorFactory.register_connector("ECExampleConnector", my_module, "MyCls")
# ValueError: Connector 'ECExampleConnector' is already registered.

# after
ECConnectorFactory._registry.pop("ECExampleConnector", None)
ECConnectorFactory.register_connector("ECExampleConnector", my_module, "MyCls")

if name in ECConnectorFactory._registry:
    ECConnectorFactory._registry.pop(name)  # intentional override
ECConnectorFactory.register_connector(name, module_path, class_name)

When it happens

Trigger: Calling register_connector('ECCPUConnector', ...) twice: e.g. the registration module being imported under two different names (package path and script path), or user code re-registering a built-in name to override it; a plugin re-running registration on hot-reload.

Common situations: Custom out-of-tree EC connectors that reuse a built-in name like 'ECExampleConnector'; test suites importing the factory module multiple times with importlib.reload; plugin systems that re-execute registration on config reload.

Related errors

• ec_transfer_config must be set for ECConnectorBase
• ec_cpu_bytes must be specified in ec_connector_extra_config
• Unknown ECConnectorRole: {role}
• Timed out waiting for EC mmap file to reach {expected_size}
• ec_transfer_config must be set for ECConnectorBase

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