vllm-project/vllm · error · ValueError

`--decode-context-parallel-size` ({decode_context_parallel_s

Error message

`--decode-context-parallel-size` ({decode_context_parallel_size}) exceeds the maximum supported value ({max_dcp_size}) for `--tensor-parallel-size` ({tensor_parallel_size}) and {total_num_kv_heads} model KV heads.

What it means

Caps decode-context-parallel-size at tensor_parallel_size // total_num_kv_heads: after reserving one TP rank per KV-head group, the remaining factor is the maximum usable DCP. Raised when the requested DCP exceeds that cap.

Source

Thrown at vllm/config/model.py:1400

                "Pipeline parallelism is not supported for this model. "
                "Supported models implement the `SupportsPP` interface."
            )

        decode_context_parallel_size = parallel_config.decode_context_parallel_size
        if decode_context_parallel_size > 1 and not self.use_mla:
            total_num_kv_heads = self.get_total_num_kv_heads()
            if tensor_parallel_size <= total_num_kv_heads:
                raise ValueError(
                    "Decode context parallelism for GQA/MQA requires "
                    f"`--tensor-parallel-size` ({tensor_parallel_size}) to be "
                    "greater than the model's total number of KV heads "
                    f"({total_num_kv_heads}). Increase `--tensor-parallel-size` "
                    "or set `--decode-context-parallel-size 1`."
                )

            max_dcp_size = tensor_parallel_size // total_num_kv_heads
            if decode_context_parallel_size > max_dcp_size:
                raise ValueError(
                    "`--decode-context-parallel-size` "
                    f"({decode_context_parallel_size}) exceeds the maximum "
                    f"supported value ({max_dcp_size}) for "
                    f"`--tensor-parallel-size` ({tensor_parallel_size}) and "
                    f"{total_num_kv_heads} model KV heads."
                )

            num_q_per_kv = total_num_attention_heads // total_num_kv_heads
            if num_q_per_kv % decode_context_parallel_size != 0:
                raise ValueError(
                    "The model's number of query heads per KV head "
                    f"({num_q_per_kv}) must be divisible by "
                    "`--decode-context-parallel-size` "
                    f"({decode_context_parallel_size}) for GQA/MQA."
                )

        # torch_shm uses a single IPC queue to rank 0; DP>1 is
        # incompatible because API servers can't know which

View on GitHub (pinned to c794754062)

Solutions

Lower --decode-context-parallel-size to at most tensor_parallel_size // num_key_value_heads.
Raise --tensor-parallel-size to increase the DCP ceiling.
Disable DCP with --decode-context-parallel-size 1 if the hardware budget is fixed.

Example fix

# before (8 KV heads, TP=16, max DCP=2)
vllm serve model --tensor-parallel-size 16 --decode-context-parallel-size 4
# after
vllm serve model --tensor-parallel-size 16 --decode-context-parallel-size 2

Defensive patterns

Strategy: validation

Validate before calling

def max_dcp(tp: int, total_kv_heads: int) -> int:
    return tp // total_kv_heads
assert dcp <= max_dcp(tp, total_kv_heads), 'DCP over budget'

Prevention

Derive --decode-context-parallel-size from tensor_parallel_size // num_key_value_heads, never hardcode it.
Re-run the arithmetic whenever TP or the checkpoint changes.
Log the computed max DCP at deploy time so misconfigurations are visible.

When it happens

Trigger: verify_with_parallel_config with DCP > 1, non-MLA model, TP > total_num_kv_heads, and decode_context_parallel_size > (tensor_parallel_size // total_num_kv_heads). E.g. 8 KV heads, TP=16 gives max DCP=2; requesting DCP=4 fails.

Common situations: Tuning DCP upward for longer contexts and hitting the arithmetic ceiling; computing allowed DCP from TP alone while forgetting the KV-head divisor.

Related errors

AI-assisted analysis of vllm-project/vllm@c794754062 (2026-08-14). Data as JSON: /api/errors/66df3e6fd6142523. Report an issue: GitHub.