{"record":{"id":"957bdc8b7213765d","repo":"vllm-project/vllm","slug":"enable-return-routed-experts-is-incompatible-wit-957bdc","errorCode":null,"errorMessage":"--enable-return-routed-experts is incompatible with context parallelism (DCP > 1 or PCP > 1).","messagePattern":"--enable-return-routed-experts is incompatible with context parallelism \\(DCP > 1 or PCP > 1\\)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/config/vllm.py","lineNumber":1081,"sourceCode":"            self.model_config.verify_with_parallel_config(self.parallel_config)\n            self.model_config.verify_dual_chunk_attention_config(self.load_config)\n\n            self.parallel_config.is_moe_model = self.model_config.is_moe\n\n        if (\n            self.model_config is not None\n            and self.model_config.enable_return_routed_experts\n        ):\n            if self.parallel_config.pipeline_parallel_size > 1:\n                raise ValueError(\n                    \"--enable-return-routed-experts is incompatible with \"\n                    \"pipeline parallelism (PP > 1).\"\n                )\n            if (\n                self.parallel_config.decode_context_parallel_size > 1\n                or self.parallel_config.prefill_context_parallel_size > 1\n            ):\n                raise ValueError(\n                    \"--enable-return-routed-experts is incompatible with context \"\n                    \"parallelism (DCP > 1 or PCP > 1).\"\n                )\n\n            # Incompatible with any KV connector — covers both PD disaggregation\n            # (kv_producer/kv_consumer: routing captured on P can't reach D) and\n            # single-instance KV offload/sharing (kv_both: slot_mapping semantics\n            # change when KV blocks live outside local GPU memory, breaking the\n            # slot-indexed routed_experts buffer).\n            if (\n                self.kv_transfer_config is not None\n                and self.kv_transfer_config.is_kv_transfer_instance\n            ):\n                raise ValueError(\n                    \"--enable-return-routed-experts is incompatible with KV \"\n                    \"connectors (PD disaggregation, KV cache offload).\"\n                )\n","sourceCodeStart":1063,"sourceCodeEnd":1099,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/config/vllm.py#L1063-L1099","documentation":"The routed-experts return feature is also rejected when context parallelism is active: decode_context_parallel_size > 1 or prefill_context_parallel_size > 1. With DCP/PCP, different ranks own different context slices, so per-slot routing decisions are fragmented across ranks and cannot populate the slot-indexed routed_experts buffer consistently. Checked immediately after the PP check for the same flag.","triggerScenarios":"Serving long-context workloads with --decode-context-parallel-size or --prefill-context-parallel-size greater than 1 while --enable-return-routed-experts is set.","commonSituations":"Long-context MoE deployments (DeepSeek-class with 128K+ context) that rely on context parallelism; enabling routing observability on a cluster already tuned for CP; mixing experimental observability flags with context-parallel serving profiles.","solutions":["Set decode_context_parallel_size=1 and prefill_context_parallel_size=1 (drop context parallelism) for the instance returning routed experts","Disable --enable-return-routed-experts on CP deployments and gather routing from a dedicated non-CP replica","Collect routing offline via router-logit dumps instead of the request-path API"],"exampleFix":"# before\nvllm serve moe-model --enable-return-routed-experts --decode-context-parallel-size 4\n# after\nvllm serve moe-model --enable-return-routed-experts  # CP disabled","handlingStrategy":"validation","validationCode":"if model_config.enable_return_routed_experts:\n    p = parallel_config\n    assert p.decode_context_parallel_size <= 1 and p.prefill_context_parallel_size <= 1, \\\n        \"routed-experts return incompatible with context parallelism\"","typeGuard":"def routed_experts_cp_ok(enabled: bool, dcp: int, pcp: int) -> bool:\n    return not enabled or (dcp <= 1 and pcp <= 1)","tryCatchPattern":null,"preventionTips":["Disable context parallelism on analysis replicas that return routed experts","Keep observability flags out of long-context CP-tuned production profiles"],"tags":["moe","context-parallelism","expert-routing","config"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}