What causes "Unknown ECConnectorRole: {role}" in vllm-project/vllm?

Pass the enum: ECConnectorRole.WORKER or ECConnectorRole.SCHEDULER

vllm-project/vllm · error · ValueError

Unknown ECConnectorRole: {role}

Error message

Unknown ECConnectorRole: {role}

What it means

ECCPUConnector dispatches on the ECConnectorRole enum in __init__: WORKER builds a connector_worker, SCHEDULER builds a connector_scheduler, and anything else (an unknown enum value or an int/str passed instead of the enum) raises ValueError. The two-role split exists because scheduler and worker processes get different connector behavior.

Source

Thrown at vllm/distributed/ec_transfer/ec_connector/cpu/connector.py:46

logger = init_logger(__name__)


class ECCPUConnector(ECConnectorBase):
    """EC connector that offloads encoder cache to a shared CPU mmap region."""

    def __init__(self, vllm_config: "VllmConfig", role: ECConnectorRole) -> None:
        super().__init__(vllm_config=vllm_config, role=role)

        self.connector_worker = None
        self.connector_scheduler = None

        if role == ECConnectorRole.WORKER:
            self.connector_worker = self._make_worker(vllm_config)
        elif role == ECConnectorRole.SCHEDULER:
            self.connector_scheduler = self._make_scheduler(vllm_config)
        else:
            raise ValueError(f"Unknown ECConnectorRole: {role}")

    # Construction seams.
    def _make_worker(self, vllm_config: "VllmConfig"):
        # Deferred import: the worker module touches torch/CUDA at import time
        # via the region, so keep that cost off the scheduler path.
        from vllm.distributed.ec_transfer.ec_connector.cpu.worker import (
            ECCPUWorker,
        )

        return ECCPUWorker(vllm_config)

    def _make_scheduler(self, vllm_config: "VllmConfig"):
        from vllm.distributed.ec_transfer.ec_connector.cpu.scheduler import (
            ECCPUScheduler,
        )

        return ECCPUScheduler(vllm_config)

View on GitHub (pinned to c794754062)

Solutions

Pass the enum: ECConnectorRole.WORKER or ECConnectorRole.SCHEDULER
Prefer ECConnectorFactory.create_connector(config, role) which is the supported construction path
If you added a new role to ECConnectorRole, add a matching branch (or convert the chain to a dispatch map) in the connector

Example fix

# before
connector = ECCPUConnector(vllm_config, role="worker")
# ValueError: Unknown ECConnectorRole: worker

# after
from vllm.distributed.ec_transfer.ec_connector.base import ECConnectorRole
connector = ECCPUConnector(vllm_config, role=ECConnectorRole.WORKER)

Defensive patterns

Strategy: type-guard

Validate before calling

from vllm.distributed.ec_transfer.ec_connector.base import ECConnectorRole
assert role in (ECConnectorRole.WORKER, ECConnectorRole.SCHEDULER)

Type guard

def is_supported_role(role) -> bool:
    return role in (ECConnectorRole.WORKER, ECConnectorRole.SCHEDULER)

Prevention

Pass ECConnectorRole enum members, never strings or ints
Construct connectors via ECConnectorFactory.create_connector
When adding enum members, update every role-dispatch chain

When it happens

Trigger: Passing a raw string like "worker" or an int instead of ECConnectorRole.WORKER/ECConnectorRole.SCHEDULER; a new ECConnectorRole member added to the enum without updating this if/elif chain; calling the connector with role=None in tests.

Common situations: Custom entrypoints constructing the connector directly instead of via ECConnectorFactory.create_connector (which validates roles); enum extensions during development of new EC roles.

Related errors

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