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.

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.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

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

Appendix: 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)