vllm-project/vllm · error · ValueError

Invalid MoRIIO backend {backend!r} in kv_connector_extra_con

Error message

Invalid MoRIIO backend {backend!r} in kv_connector_extra_config; must be one of 'rdma' or 'xgmi'.

What it means

MoRIIO connector config validates the 'backend' field of kv_connector_extra_config: after str(...).lower() it must be 'rdma' or 'xgmi' (xgmi = intra-node GPU-to-GPU over AMD GMI / NVLink-class links). Any other spelling or value raises ValueError at worker init.

Source

Thrown at vllm/distributed/kv_transfer/kv_connector/v1/moriio/moriio_common.py:311

        # TODO : merge notify_port and handshake_port to simplify port management
        #        supports non-contiguous ports
        assert vllm_config.kv_transfer_config is not None, (
            "kv_transfer_config must be set for MoRIIOConnector"
        )
        _warn_deprecated_env_vars()
        kv_transfer_config = vllm_config.kv_transfer_config
        extra_config = kv_transfer_config.kv_connector_extra_config
        tp_rank = get_tensor_model_parallel_rank()
        # Fold the global data_parallel_rank back to [0, dp_size_local) for
        # per-node port allocation (handles the external-DP sentinel).
        pc = vllm_config.parallel_config
        dp_rank = fold_local_rank(pc.data_parallel_rank, pc.data_parallel_size_local)
        base_notify_port = int(extra_config["notify_port"])
        tp_size = get_tensor_model_parallel_world_size()
        port_offset = get_port_offset(dp_rank, tp_rank)
        backend = str(extra_config.get("backend", "rdma")).lower()
        if backend not in ("rdma", "xgmi"):
            raise ValueError(
                f"Invalid MoRIIO backend {backend!r} in kv_connector_extra_config; "
                "must be one of 'rdma' or 'xgmi'."
            )

        transfer_timeout = float(
            extra_config.get(
                "transfer_timeout", MoRIIOConstants.DEFAULT_TRANSFER_TIMEOUT
            )
        )
        defer_timeout = float(
            extra_config.get("defer_timeout", MoRIIOConstants.DEFAULT_DEFER_TIMEOUT)
        )

        return cls(
            local_ip=resolve_host_ip(extra_config),
            local_kv_port=get_open_port(),
            proxy_ip=extra_config.get("proxy_ip", ""),
            local_ping_port=get_open_port(),

View on GitHub (pinned to c794754062)

Solutions

1. Use "backend": "rdma" for inter-node RDMA or "backend": "xgmi" for intra-node transfers
2. Remove the key entirely — it defaults to 'rdma'
3. Check for stray whitespace/case in the YAML value (only case is normalized, whitespace is not)

Example fix

# before
kv_connector_extra_config={"backend": "tcp", "notify_port": 5555}

# after
kv_connector_extra_config={"backend": "rdma", "notify_port": 5555}

backend = str(extra_config.get("backend", "rdma")).lower()
if backend not in ("rdma", "xgmi"):
    raise ValueError("MoRIIO backend must be 'rdma' or 'xgmi'")

def is_valid_moriio_backend(v) -> bool:
    return isinstance(v, str) and v.strip().lower() in ("rdma", "xgmi")

When it happens

Trigger: kv_connector_extra_config={'backend': 'TCP'}, 'ib', 'nvlink', or a typo like 'Rdma ' that lower() does not fix (trailing space is not stripped).

Common situations: Copying NIXL/Mooncake vocabulary ('tcp') into MoRIIO config; assuming NVLink is spelled out; trailing whitespace from YAML templates.

Related errors

• HTTP request failed: {0}
• JSON error: {0}
• Tokenizer error: {0}
• kv_connector_module_path cannot be an empty string.
• Mooncake Transfer Engine initialization failed.

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