sgl-project/sglang · error · ValueError

Unsupported transfer backend: {transfer_backend}

Error message

Unsupported transfer backend: {transfer_backend}

What it means

get_kv_class maps a transfer backend string (e.g. 'mooncake', 'nixl', 'fake', '') to KV manager/sender/receiver classes for disaggregated KV transfer. Any backend name not in the known mapping raises ValueError with the unsupported name.

Source

Thrown at python/sglang/srt/disaggregation/utils.py:693

            KVClassType.SENDER: NixlKVSender,
            KVClassType.RECEIVER: NixlKVReceiver,
            KVClassType.BOOTSTRAP_SERVER: NixlKVBootstrapServer,
        }
    elif transfer_backend == TransferBackend.FAKE:
        from sglang.srt.disaggregation.fake import (
            FakeKVManager,
            FakeKVReceiver,
            FakeKVSender,
        )

        # No bootstrap server: the fake backend never registers one.
        class_mapping = {
            KVClassType.MANAGER: FakeKVManager,
            KVClassType.SENDER: FakeKVSender,
            KVClassType.RECEIVER: FakeKVReceiver,
        }
    else:
        raise ValueError(f"Unsupported transfer backend: {transfer_backend}")

    return class_mapping.get(class_type)


def _get_cp_rank_page_bounds(
    total_pages: int, cp_rank: int, cp_size: int
) -> Tuple[int, int]:
    base = total_pages // cp_size
    rem = total_pages % cp_size
    local_start = cp_rank * base + min(cp_rank, rem)
    n_pages = base + (1 if cp_rank < rem else 0)
    return local_start, local_start + n_pages


def filter_kv_indices_for_cp_rank(
    kv_mgr: CommonKVManager,
    kv_indices: np.ndarray,
    index_slice: slice,

View on GitHub (pinned to 0132848349)

Solutions

1. Check the spelling/case of --disaggregation-transfer-backend against supported values (e.g. mooncake, nixl, fake)
2. Upgrade sglang to a version that supports the backend you want
3. If a custom backend exists, register/alias it in get_kv_class's mapping or use its exact name

Example fix

# before
--disaggregation-transfer-backend NIXL
# after
--disaggregation-transfer-backend nixl

SUPPORTED = {"", "mooncake", "nixl", "fake"}  # keep in sync with get_kv_class
assert server_args.disaggregation_transfer_backend in SUPPORTED, f"unsupported backend {server_args.disaggregation_transfer_backend}"

try:
    cls = get_kv_class(backend, class_type)
except ValueError as e:
    raise SystemExit(f"Bad --disaggregation-transfer-backend: {e}") from e

When it happens

Trigger: Passing a misspelled or unknown --disaggregation-transfer-backend value to server args, e.g. 'Nixl', 'rdma', or a backend compiled out of the current build; get_kv_class then falls through all elif branches to the final raise.

Common situations: Typos in launch scripts, case mismatches, backends introduced in newer SGLang versions used on an older install, or custom transfer backends registered under a different name.

Related errors

• mooncake encoder_transfer_backend requires HTTP encoders; us
• PD state transfer failed: kv_args.state_types is empty but s
• Unsupported content type ${header.content_type}
• Unknown serve backend {name!r}. Available values: {available
• k_cache can only be None when only_qv=True

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/e66e513405533cac. Report an issue: GitHub.