What causes "Unknown all2all backend: {self.all2all_backend}" in vllm-project/vllm?

Use one of the exact names handled in cuda_communicator.py (e.g. flashinfer_nvlink_two_sided, flashinfer_nvlink_one_sided).

vllm-project/vllm · error · ValueError

Unknown all2all backend: {self.all2all_backend}

Error message

Unknown all2all backend: {self.all2all_backend}

What it means

Raised by CudaCommunicator when the configured all2all_backend string matches none of the known options (the if/elif chain for flashinfer_nvlink_two_sided / flashinfer_nvlink_one_sided / etc. falls through). The backend name comes from distributed config, so an unrecognized value fails fast at communicator construction.

Source

Thrown at vllm/distributed/device_communicators/cuda_communicator.py:201

                or self.all2all_backend == "flashinfer_nvlink_two_sided"
            ):
                if self.all2all_backend == "flashinfer_all2allv":
                    logger.warning_once(
                        "'flashinfer_all2allv' is deprecated and has been renamed to"
                        "'flashinfer_nvlink_two_sided'. It will be removed in a future"
                        "release."
                    )
                from .all2all import FlashInferNVLinkTwoSidedManager

                self.all2all_manager = FlashInferNVLinkTwoSidedManager(
                    self.cpu_group, tcp_store_group
                )
            elif self.all2all_backend == "flashinfer_nvlink_one_sided":
                from .all2all import FlashInferNVLinkOneSidedManager

                self.all2all_manager = FlashInferNVLinkOneSidedManager(self.cpu_group)
            else:
                raise ValueError(f"Unknown all2all backend: {self.all2all_backend}")

            logger.info_once(
                "Using %s all2all manager.",
                self.all2all_manager.__class__.__name__,
                scope="global",
            )

    def _log_all_reduce_backend_selection(self) -> None:
        """Log the all-reduce backends that are active for this group.

        The dispatch chain in ``all_reduce`` tries backends in this order and
        falls through to the next one if the current backend rejects the
        input (size/dtype gates) or is disabled. The list of "enabled"
        backends below is the subset of potential backends that may be
        chosen at dispatch time for this group; the actual per-call choice
        depends on the input tensor.
        """
        all_potential_ar_backends = [

View on GitHub (pinned to c794754062)

Solutions

Use one of the exact names handled in cuda_communicator.py (e.g. flashinfer_nvlink_two_sided, flashinfer_nvlink_one_sided).
Clear the all2all backend setting if you did not intend to configure it, letting the default path apply.
Align vLLM version with the config source (names are per-version); check the current file for the accepted values.

Example fix

# before
--distributed-config '{"all2all_backend":"flashinfer-nvlink-2s"}'
# after
--distributed-config '{"all2all_backend":"flashinfer_nvlink_two_sided"}'

Defensive patterns

Strategy: validation

Validate before calling

VALID = {"flashinfer_nvlink_two_sided", "flashinfer_nvlink_one_sided"}
name = dist_cfg.all2all_backend
if name is not None and name not in VALID:
    raise SystemExit(f"unknown all2all backend {name!r}; valid: {sorted(VALID)}")

Type guard

def all2all_backend_known(name: str) -> bool:
    return name in {"flashinfer_nvlink_two_sided", "flashinfer_nvlink_one_sided"}

Try / catch

try:
    comm = CudaCommunicator(group, all2all_backend=name)
except ValueError as e:
    if "Unknown all2all backend" in str(e):
        name = None  # fall back to default dispatch
        comm = CudaCommunicator(group)
    else:
        raise

Prevention

Validate all2all backend strings against the names in the deployed vLLM's cuda_communicator.py before launch.
Regenerate config templates on vLLM upgrades — backend names change between versions.

When it happens

Trigger: Passing a misspelled or version-mismatched all2all backend (e.g. 'flashinfer-nvlink', 'one_sided', or a name introduced in another vLLM version) via --distributed-config / VLLM_ALL2ALL_BACKEND equivalent settings while creating a CudaCommunicator with all2all enabled.

Common situations: Copying configs between vLLM versions where backend names changed; typos in YAML/JSON distributed config; plugins expecting to inject custom names that core does not know.

Related errors

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