{"record":{"id":"9d4e36741d995003","repo":"vllm-project/vllm","slug":"ec-transfer-config-must-be-set-for-ecconnectorbase-9d4e36","errorCode":null,"errorMessage":"ec_transfer_config must be set for ECConnectorBase","messagePattern":"ec_transfer_config must be set for ECConnectorBase","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/distributed/ec_transfer/ec_connector/example_connector.py","lineNumber":64,"sourceCode":"class ECExampleConnector(ECConnectorBase):\n    # NOTE: This is Simple debug implementation of the EC connector.\n    # It save / load the EC cache to / from the disk.\n\n    def __init__(self, vllm_config: \"VllmConfig\", role: ECConnectorRole):\n        super().__init__(vllm_config=vllm_config, role=role)\n        # req_id -> index\n        self._mm_datas_need_loads: dict[str, int] = {}\n        self._model_config = vllm_config.model_config\n        self._metadata_fields_cache: dict[str, set[str]] = {}\n        transfer_config = vllm_config.ec_transfer_config\n        if transfer_config is not None:\n            self._storage_path = transfer_config.get_from_extra_config(\n                \"shared_storage_path\", \"/tmp\"\n            )\n            logger.debug(transfer_config)\n            logger.debug(\"Shared storage path is %s\", self._storage_path)\n        else:\n            raise ValueError(\"ec_transfer_config must be set for ECConnectorBase\")\n\n    def start_load_caches(self, encoder_cache, **kwargs) -> None:\n        \"\"\"\n        Start loading the cache from the connector into vLLM's encoder cache.\n\n        This method loads the encoder cache based on metadata provided by the scheduler.\n        It is called before `_gather_mm_embeddings` for the EC Connector. For EC,\n        the `encoder_cache` and `mm_hash` are stored in `kwargs`.\n\n        Args:\n            encoder_cache (dict[str, torch.Tensor]): A dictionary mapping multimodal\n                data hashes (`mm_hash`) to encoder cache tensors.\n            kwargs (dict): Additional keyword arguments for the connector.\n        \"\"\"\n        from vllm.platforms import current_platform\n\n        # Get the metadata\n        metadata: ECConnectorMetadata = self._get_connector_metadata()","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/distributed/ec_transfer/ec_connector/example_connector.py#L46-L82","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set ec_transfer_config on VllmConfig before constructing the connector","When using the example connector, also set 'shared_storage_path' in the extra config (it defaults to /tmp)","In standalone scripts, build a minimal ECTransferConfig and attach it before connector construction"],"exampleFix":"# before\nconnector = ECExampleConnector(vllm_config)  # ec_transfer_config is None\n\n# after\nvllm_config.ec_transfer_config = ECTransferConfig(\n    ec_connector=\"ECExampleConnector\",\n    ec_connector_extra_config={\"shared_storage_path\": \"/data/ec_cache\"},\n)\nconnector = ECExampleConnector(vllm_config)","handlingStrategy":"validation","validationCode":"if vllm_config.ec_transfer_config is None:\n    raise RuntimeError(\"ECTransferConfig required before ECExampleConnector\")\nassert vllm_config.ec_transfer_config.get_from_extra_config(\"shared_storage_path\")","typeGuard":"def ec_example_ready(vllm_config) -> bool:\n    cfg = getattr(vllm_config, \"ec_transfer_config\", None)\n    return cfg is not None and cfg.get_from_extra_config(\"shared_storage_path\") is not None","tryCatchPattern":null,"preventionTips":["Set both the config object and shared_storage_path before constructing the example connector","Use one shared config-builder helper for all EC connectors in your codebase","Add smoke tests that construct each connector you enable"],"tags":["configuration","ec-transfer","api-misuse"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}