{"record":{"id":"66df3e6fd6142523","repo":"vllm-project/vllm","slug":"decode-context-parallel-size-decode-context","errorCode":null,"errorMessage":"`--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.","messagePattern":"`--decode-context-parallel-size` \\((.+?)\\) exceeds the maximum supported value \\((.+?)\\) for `--tensor-parallel-size` \\((.+?)\\) and (.+?) model KV heads\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/config/model.py","lineNumber":1400,"sourceCode":"                \"Pipeline parallelism is not supported for this model. \"\n                \"Supported models implement the `SupportsPP` interface.\"\n            )\n\n        decode_context_parallel_size = parallel_config.decode_context_parallel_size\n        if decode_context_parallel_size > 1 and not self.use_mla:\n            total_num_kv_heads = self.get_total_num_kv_heads()\n            if tensor_parallel_size <= total_num_kv_heads:\n                raise ValueError(\n                    \"Decode context parallelism for GQA/MQA requires \"\n                    f\"`--tensor-parallel-size` ({tensor_parallel_size}) to be \"\n                    \"greater than the model's total number of KV heads \"\n                    f\"({total_num_kv_heads}). Increase `--tensor-parallel-size` \"\n                    \"or set `--decode-context-parallel-size 1`.\"\n                )\n\n            max_dcp_size = tensor_parallel_size // total_num_kv_heads\n            if decode_context_parallel_size > max_dcp_size:\n                raise ValueError(\n                    \"`--decode-context-parallel-size` \"\n                    f\"({decode_context_parallel_size}) exceeds the maximum \"\n                    f\"supported value ({max_dcp_size}) for \"\n                    f\"`--tensor-parallel-size` ({tensor_parallel_size}) and \"\n                    f\"{total_num_kv_heads} model KV heads.\"\n                )\n\n            num_q_per_kv = total_num_attention_heads // total_num_kv_heads\n            if num_q_per_kv % decode_context_parallel_size != 0:\n                raise ValueError(\n                    \"The model's number of query heads per KV head \"\n                    f\"({num_q_per_kv}) must be divisible by \"\n                    \"`--decode-context-parallel-size` \"\n                    f\"({decode_context_parallel_size}) for GQA/MQA.\"\n                )\n\n        # torch_shm uses a single IPC queue to rank 0; DP>1 is\n        # incompatible because API servers can't know which","sourceCodeStart":1382,"sourceCodeEnd":1418,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/config/model.py#L1382-L1418","documentation":"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.","triggerScenarios":"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.","commonSituations":"Tuning DCP upward for longer contexts and hitting the arithmetic ceiling; computing allowed DCP from TP alone while forgetting the KV-head divisor.","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."],"exampleFix":"# before (8 KV heads, TP=16, max DCP=2)\nvllm serve model --tensor-parallel-size 16 --decode-context-parallel-size 4\n# after\nvllm serve model --tensor-parallel-size 16 --decode-context-parallel-size 2","handlingStrategy":"validation","validationCode":"def max_dcp(tp: int, total_kv_heads: int) -> int:\n    return tp // total_kv_heads\nassert dcp <= max_dcp(tp, total_kv_heads), 'DCP over budget'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["parallelism","decode-context-parallel","gqa","config"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}