sgl-project/sglang · error · ValueError

--dcp-replicate-q-proj only applies to the a2a/fi_a2a DCP co

Error message

--dcp-replicate-q-proj only applies to the a2a/fi_a2a DCP communication backend (it removes the head-dim Q all-gather); got --dcp-comm-backend={cfg.dcp_comm_backend}.

What it means

ServerArgs validation error raised when --dcp-replicate-q-proj is combined with a DCP communication backend other than a2a or fi_a2a. The optimization works by removing the head-dim Q all-gather, which is a structural detail of the all-to-all backends only; with ag_rs (AllGather + reduce-scatter) it does not apply.

Source

Thrown at python/sglang/srt/server_args.py:4280

            raise ValueError(
                f"--dcp-comm-backend {cfg.dcp_comm_backend} only affects the "
                "decode context-parallel attention reduction and therefore "
                "requires --dcp-size / --decode-context-parallel-size > 1, but "
                f"got dcp_size={cfg.dcp_size}."
            )
        if cfg.dcp_comm_backend == "fi_a2a" and not is_cuda():
            raise ValueError(
                "--dcp-comm-backend fi_a2a delegates the exchange to FlashInfer's "
                "MNNVL All-to-All kernel, which requires an NVIDIA CUDA platform "
                "with SM90+ and MNNVL fabric memory (e.g. GB200 NVL72). The "
                "authoritative fabric probe runs at model-runner init; use 'a2a' "
                "or 'ag_rs' on clusters without MNNVL."
            )
        if cfg.dcp_replicate_q_proj:
            if cfg.dcp_size <= 1:
                raise ValueError("--dcp-replicate-q-proj requires --dcp-size > 1.")
            if cfg.dcp_comm_backend not in ("a2a", "fi_a2a"):
                raise ValueError(
                    "--dcp-replicate-q-proj only applies to the a2a/fi_a2a DCP "
                    "communication backend (it removes the head-dim Q all-gather); "
                    f"got --dcp-comm-backend={cfg.dcp_comm_backend}."
                )

    def _handle_load_balance_method(self):
        cfg = resolving_view(self)
        if cfg.disaggregation_mode not in ("null", "prefill", "decode"):
            raise ValueError(f"Invalid disaggregation_mode={cfg.disaggregation_mode!r}")

        if cfg.load_balance_method == "auto":
            # Default behavior:
            # - non-PD: round_robin
            # - PD prefill: follow_bootstrap_room
            # - PD decode: round_robin
            self._declare(
                "_handle_load_balance_method",
                load_balance_method=(

View on GitHub (pinned to 0132848349)

Solutions

  1. Set --dcp-comm-backend a2a (portable) or fi_a2a (SM90+/MNNVL only)
  2. Or drop --dcp-replicate-q-proj if you must keep ag_rs

Example fix

# before
python -m sglang.launch_server --dcp-size 4 --dcp-comm-backend ag_rs --dcp-replicate-q-proj
# after
python -m sglang.launch_server --dcp-size 4 --dcp-comm-backend a2a --dcp-replicate-q-proj
Defensive patterns

Strategy: validation

Validate before calling

A2A_BACKENDS = {"a2a", "fi_a2a"}

def q_proj_allowed(backend: str, dcp_size: int) -> bool:
    return dcp_size > 1 and backend in A2A_BACKENDS

Prevention

When it happens

Trigger: Launching with --dcp-replicate-q-proj and --dcp-comm-backend set to ag_rs (or any value outside (a2a, fi_a2a)).

Common situations: Toggling the comm backend while keeping other DCP tuning flags; mixing recommendations from different tuning guides; using fi_a2a on non-MNNVL hardware, falling back to ag_rs but forgetting the q-proj flag.

Related errors

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