sgl-project/sglang · error · ValueError

SGLANG_DISAGG_STAGING_BUFFER requires disaggregation_transfe

Error message

SGLANG_DISAGG_STAGING_BUFFER requires disaggregation_transfer_backend='mooncake' or 'nixl', got '{}'.

What it means

The SGLANG_DISAGG_STAGING_BUFFER env var enables a staging-buffer KV transfer path that only the mooncake and nixl backends implement. Setting it with any other disaggregation transfer backend fails validation in PD modes.

Source

Thrown at python/sglang/srt/arg_groups/pd_disaggregation_hook.py:142

                server_args,
                "handle_pd_disaggregation",
                disaggregation_decode_extra_slots=extra_slots,
            )

    elif cfg.disaggregation_mode == "prefill":
        assert (
            cfg.disaggregation_transfer_backend != "fake"
        ), "Prefill server does not support 'fake' as the transfer backend"

        if envs.SGLANG_RUST_SERVER.get():
            _alias_bootstrap_port_to_api_port(server_args)

    if cfg.disaggregation_mode in ("prefill", "decode"):
        if (
            envs.SGLANG_DISAGG_STAGING_BUFFER.get()
            and cfg.disaggregation_transfer_backend not in ("mooncake", "nixl")
        ):
            raise ValueError(
                f"SGLANG_DISAGG_STAGING_BUFFER requires "
                f"disaggregation_transfer_backend='mooncake' or 'nixl', "
                f"got '{cfg.disaggregation_transfer_backend}'."
            )


def _alias_bootstrap_port_to_api_port(server_args: ServerArgs) -> None:
    """Rust-server prefill serves the KV bootstrap registry on the api listener
    itself, so the resolved bootstrap port must BE the api port — every internal
    consumer (KVManager registration, PrefillBootstrapQueue) reads the resolved
    field and agrees automatically. Decode is untouched: there the field names
    the PREFILL side's bootstrap port and must stay as the operator set it.
    """
    cfg = resolving_view(server_args)
    default_port = next(
        f.default
        for f in dataclasses.fields(server_args)
        if f.name == "disaggregation_bootstrap_port"

View on GitHub (pinned to 0132848349)

Solutions

1. Unset SGLANG_DISAGG_STAGING_BUFFER
2. Or switch --disaggregation-transfer-backend to mooncake or nixl

Example fix

# before
SGLANG_DISAGG_STAGING_BUFFER=1 --disaggregation-transfer-backend <other>
# after
SGLANG_DISAGG_STAGING_BUFFER=1 --disaggregation-transfer-backend mooncake

import os
if os.environ.get("SGLANG_DISAGG_STAGING_BUFFER") and cfg.disaggregation_transfer_backend not in ("mooncake", "nixl"):
    del os.environ["SGLANG_DISAGG_STAGING_BUFFER"]

When it happens

Trigger: Exporting SGLANG_DISAGG_STAGING_BUFFER=1 (or any truthy value) while --disaggregation-transfer-backend is not mooncake or nixl, in prefill/decode mode.

Common situations: Copying performance-tuning env vars from a mooncake-based deployment onto nodes using a different transfer backend; stale env in container images.

Related errors

• PD decode DCP requires --disaggregation-transfer-backend moo
• SGLANG_DISAGG_STAGING_BUFFER does not support prefill contex
• SGLANG_ROLE_NAMESPACES={value!r} is not one of off / record
• --disaggregation-decode-retraction-backup=host_pool is only
• The argument disaggregation-decode-enable-offload-kvcache is

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