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

ECExampleConnector (the reference encoder-cache transfer connector) reads its shared_storage_path from vllm_config.ec_transfer_config.get_from_extra_config(...). If ec_transfer_config is None it cannot resolve where to read/write cache files, so __init__ raises ValueError — the same contract as ECConnectorBase but re-implemented in the example connector.

Source

Thrown at vllm/distributed/ec_transfer/ec_connector/example_connector.py:64

class ECExampleConnector(ECConnectorBase):
    # NOTE: This is Simple debug implementation of the EC connector.
    # It save / load the EC cache to / from the disk.

    def __init__(self, vllm_config: "VllmConfig", role: ECConnectorRole):
        super().__init__(vllm_config=vllm_config, role=role)
        # req_id -> index
        self._mm_datas_need_loads: dict[str, int] = {}
        self._model_config = vllm_config.model_config
        self._metadata_fields_cache: dict[str, set[str]] = {}
        transfer_config = vllm_config.ec_transfer_config
        if transfer_config is not None:
            self._storage_path = transfer_config.get_from_extra_config(
                "shared_storage_path", "/tmp"
            )
            logger.debug(transfer_config)
            logger.debug("Shared storage path is %s", self._storage_path)
        else:
            raise ValueError("ec_transfer_config must be set for ECConnectorBase")

    def start_load_caches(self, encoder_cache, **kwargs) -> None:
        """
        Start loading the cache from the connector into vLLM's encoder cache.

        This method loads the encoder cache based on metadata provided by the scheduler.
        It is called before `_gather_mm_embeddings` for the EC Connector. For EC,
        the `encoder_cache` and `mm_hash` are stored in `kwargs`.

        Args:
            encoder_cache (dict[str, torch.Tensor]): A dictionary mapping multimodal
                data hashes (`mm_hash`) to encoder cache tensors.
            kwargs (dict): Additional keyword arguments for the connector.
        """
        from vllm.platforms import current_platform

        # Get the metadata
        metadata: ECConnectorMetadata = self._get_connector_metadata()

View on GitHub (pinned to c794754062)

Solutions

1. Set ec_transfer_config on VllmConfig before constructing the connector
2. When using the example connector, also set 'shared_storage_path' in the extra config (it defaults to /tmp)
3. In standalone scripts, build a minimal ECTransferConfig and attach it before connector construction

Example fix

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

# after
vllm_config.ec_transfer_config = ECTransferConfig(
    ec_connector="ECExampleConnector",
    ec_connector_extra_config={"shared_storage_path": "/data/ec_cache"},
)
connector = ECExampleConnector(vllm_config)

if vllm_config.ec_transfer_config is None:
    raise RuntimeError("ECTransferConfig required before ECExampleConnector")
assert vllm_config.ec_transfer_config.get_from_extra_config("shared_storage_path")

def ec_example_ready(vllm_config) -> bool:
    cfg = getattr(vllm_config, "ec_transfer_config", None)
    return cfg is not None and cfg.get_from_extra_config("shared_storage_path") is not None

When it happens

Trigger: Constructing ECExampleConnector from a VllmConfig with ec_transfer_config=None; tests or custom orchestrators building the connector directly without enabling EC transfer; running the example connector's load path without the feature flag that populates the config.

Common situations: Copy-pasting the example connector into a custom setup while skipping the config plumbing; enabling the connector by name (ec_connector='ECExampleConnector') without the surrounding EC transfer options.

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/9d4e36741d995003. Report an issue: GitHub.