sgl-project/sglang · error · ValueError

--dcp-replicate-q-proj requires --dcp-size > 1.

Error message

--dcp-replicate-q-proj requires --dcp-size > 1.

What it means

ServerArgs validation error raised when --dcp-replicate-q-proj is enabled but --dcp-size (--decode-context-parallel-size) is 1 or unset. Replicating the Q projection across DCP ranks only makes sense when decode context parallelism actually shards the batch across multiple ranks, so SGLang rejects the flag as meaningless without it.

Source

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

            )
        if cfg.dcp_comm_backend in ("a2a", "fi_a2a") and cfg.dcp_size <= 1:
            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(

View on GitHub (pinned to 0132848349)

Solutions

  1. Set --dcp-size (or --decode-context-parallel-size) to a value > 1, e.g. --dcp-size 4
  2. If you do not intend to use decode context parallelism, remove --dcp-replicate-q-proj entirely

Example fix

# before
python -m sglang.launch_server --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

def dcp_flags(dcp_size: int, replicate_q: bool) -> list[str]:
    flags = [f"--dcp-size", str(dcp_size)] if dcp_size > 1 else []
    if replicate_q:
        assert dcp_size > 1, "--dcp-replicate-q-proj requires --dcp-size > 1"
        flags.append("--dcp-replicate-q-proj")
    return flags

Prevention

When it happens

Trigger: Launching with --dcp-replicate-q-proj while dcp_size <= 1 (flag omitted or set to 1).

Common situations: Copy-pasting a tuned DCP flag set but forgetting --dcp-size; enabling the optimization in a single-rank smoke test; leftover flag from a previous experiment after removing DCP.

Related errors

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