vllm-project/vllm · error · ValueError

ec_transfer_config must be set for ECConnectorBase

Error message

ec_transfer_config must be set for ECConnectorBase

What it means

ECConnectorBase (base class for encoder-cache transfer connectors) requires vllm_config.ec_transfer_config to be set, because it derives its is_producer/is_consumer role flags from it. Constructing any EC connector without an ECTransferConfig means the connector cannot know which side of the producer/consumer split it is on, so __init__ raises ValueError.

Source

Thrown at vllm/distributed/ec_transfer/ec_connector/base.py:68

class ECConnectorMetadata(ABC):  # noqa: B024
    """
    Abstract Metadata used to communicate between the
    Scheduler ECConnector and Worker ECConnector.
    """

    pass


class ECConnectorBase(ABC):
    def __init__(self, vllm_config: "VllmConfig", role: ECConnectorRole):
        self._connector_metadata: ECConnectorMetadata | None = None
        self._vllm_config = vllm_config
        self._role = role
        if vllm_config.ec_transfer_config is not None:
            self._is_producer = vllm_config.ec_transfer_config.is_ec_producer
            self._is_consumer = vllm_config.ec_transfer_config.is_ec_consumer
        else:
            raise ValueError("ec_transfer_config must be set for ECConnectorBase")

    @property
    def role(self) -> ECConnectorRole:
        return self._role

    @property
    def is_producer(self) -> bool:
        return self._is_producer

    @property
    def is_consumer(self) -> bool:
        return self._is_consumer

    def shutdown(self) -> None:
        """
        Shutdown the connector. This is called when the process
        is shutting down to ensure that all the async operations are
        completed and the connector is cleaned up properly.

View on GitHub (pinned to c794754062)

Solutions

1. Set ec_transfer_config on the VllmConfig before constructing the connector (enable the EC transfer feature via its documented CLI/env option so the config is populated)
2. In tests, construct a minimal ECTransferConfig with is_ec_producer/is_ec_consumer set and assign it to the config
3. Guard construction: only build connectors when vllm_config.ec_transfer_config is not None

Example fix

# before
connector = ECCPUConnector(vllm_config)  # ec_transfer_config is None

# after
from vllm.config import ECTransferConfig
vllm_config.ec_transfer_config = ECTransferConfig(is_ec_producer=True)
connector = ECCPUConnector(vllm_config)

if vllm_config.ec_transfer_config is None:
    raise RuntimeError("enable EC transfer before constructing EC connectors")

def has_ec_config(vllm_config) -> bool:
    return getattr(vllm_config, "ec_transfer_config", None) is not None

When it happens

Trigger: Instantiating a CPU/example EC connector from a VllmConfig that has ec_transfer_config=None; programmatic construction of a connector in tests or tooling that builds a partial VllmConfig; enabling the EC transfer feature without wiring the config object.

Common situations: Writing unit tests that build VllmConfig() defaults and then construct ECConnector classes; integrating EC transfer into a custom entrypoint that forgets to set ec_transfer_config; version upgrades where the config became mandatory for this path.

Related errors

• ec_transfer_config must be set for ECConnectorBase
• PostGradPassManager can not be kept in CompilationConfig.
• Lock must be provided for readers.
• ec_cpu_bytes must be specified in ec_connector_extra_config
• Unknown ECConnectorRole: {role}

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