What causes "EC connect must not be None" in vllm-project/vllm?

Set ec_connector on ECTransferConfig to a registered name (e.g. 'ECExampleConnector') or a class name resolvable via ec_connector_module_path

vllm-project/vllm · error · ValueError

EC connect must not be None

Error message

EC connect must not be None

What it means

get_connector_class() resolves which class to instantiate from ec_transfer_config.ec_connector. A None connector name means the config exists but no connector was chosen, and there is no default to fall back to, so it raises ValueError (the message has a small typo: 'EC connect' instead of 'EC connector').

Source

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

            connector_cls.__name__,
            ec_transfer_config.engine_id,
        )
        # Connector is explicitly separated into two roles.
        # Scheduler connector:
        # - Co-locate with scheduler process
        # - Should only be used inside the Scheduler class
        # Worker connector:
        # - Co-locate with worker process
        return connector_cls(config, role)

    @classmethod
    def get_connector_class(
        cls, ec_transfer_config: "ECTransferConfig"
    ) -> type[ECConnectorBase]:
        """Get the connector class by name."""
        connector_name = ec_transfer_config.ec_connector
        if connector_name is None:
            raise ValueError("EC connect must not be None")
        elif connector_name in cls._registry:
            connector_cls = cls._registry[connector_name]()
        else:
            connector_module_path = ec_transfer_config.ec_connector_module_path
            if connector_module_path is None:
                raise ValueError(f"Unsupported connector type: {connector_name}")
            connector_module = importlib.import_module(connector_module_path)
            connector_cls = getattr(connector_module, connector_name)
        return connector_cls


# Register various connectors here.
# The registration should not be done in each individual file, as we want to
# only load the files corresponding to the current connector.

ECConnectorFactory.register_connector(
    "ECExampleConnector",
    "vllm.distributed.ec_transfer.ec_connector.example_connector",

View on GitHub (pinned to c794754062)

Solutions

Set ec_connector on ECTransferConfig to a registered name (e.g. 'ECExampleConnector') or a class name resolvable via ec_connector_module_path
Validate the config early: assert ec_transfer_config.ec_connector before entering the EC path
For custom connectors, also set ec_connector_module_path so the fallback import works

Example fix

# before
ECTransferConfig(is_ec_producer=True)  # ec_connector is None
# ValueError: EC connect must not be None

# after
ECTransferConfig(is_ec_producer=True, ec_connector="ECExampleConnector")

Defensive patterns

Strategy: validation

Validate before calling

name = ec_transfer_config.ec_connector
assert name, "set ec_transfer_config.ec_connector before creating a connector"

Type guard

def has_connector_name(ec_transfer_config) -> bool:
    return ec_transfer_config.ec_connector is not None

Prevention

Always set ec_connector when constructing ECTransferConfig for real use
Validate required EC fields in one place at startup
Add a config schema check that rejects None connector names on the EC path

When it happens

Trigger: Creating an ECTransferConfig with ec_connector unset/None but still calling create_connector; constructing the config for its consumer/producer role flags only and accidentally entering connector creation; config parsing that drops an empty --ec-connector value to None.

Common situations: Setting only ec_cpu_bytes/role flags in extra config while forgetting the connector name; programmatic configs built field-by-field that skip ec_connector.

Related errors

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