{"record":{"id":"6ccefdc2467b901f","repo":"vllm-project/vllm","slug":"enable-return-routed-experts-is-incompatible-wit","errorCode":null,"errorMessage":"--enable-return-routed-experts is incompatible with pipeline parallelism (PP > 1).","messagePattern":"--enable-return-routed-experts is incompatible with pipeline parallelism \\(PP > 1\\)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/config/vllm.py","lineNumber":1073,"sourceCode":"        self.instance_id = f\"{time.time_ns()}\"\n\n        if self.performance_mode != \"balanced\":\n            logger.info_once(\"Performance mode set to '%s'.\", self.performance_mode)\n\n        self.try_verify_and_update_config()\n\n        if self.model_config is not None:\n            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 (","sourceCodeStart":1055,"sourceCodeEnd":1091,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/config/vllm.py#L1055-L1091","documentation":"VllmConfig rejects --enable-return-routed-experts (model_config.enable_return_routed_experts, which returns per-token expert-routing decisions for MoE analysis) when pipeline_parallel_size > 1. The routed-experts buffer is indexed by request slot across a single engine instance; with PP > 1 the request is split across pipeline stages and the routing captured on one rank cannot be assembled into the slot-indexed response on the others. The check runs in __post_init__ right after parallel-config verification.","triggerScenarios":"Launching a large MoE model sharded across pipeline stages (e.g. --pipeline-parallel-size 4) together with --enable-return-routed-experts.","commonSituations":"Serving a big MoE (DeepSeek/Mixtral-class) that needs PP to fit in memory while also wanting expert-routing telemetry; enabling the observability flag fleet-wide including multi-node PP deployments; research setups collecting routing statistics from production-shaped clusters.","solutions":["Drop pipeline parallelism (set pipeline_parallel_size=1) and use tensor/EP parallelism instead to fit the model","Disable --enable-return-routed-experts on PP deployments; collect routing from a separate non-PP analysis instance","Sample routing offline via instrumentation (hooks/dump of router logits) rather than the serving-path API"],"exampleFix":"# before\nvllm serve moe-model --enable-return-routed-experts -pp 4 -tp 2\n# after\nvllm serve moe-model --enable-return-routed-experts -tp 8  # no PP","handlingStrategy":"validation","validationCode":"if model_config.enable_return_routed_experts:\n    assert parallel_config.pipeline_parallel_size == 1, \\\n        \"routed-experts return incompatible with PP > 1\"","typeGuard":"def routed_experts_pp_ok(enabled: bool, pp: int) -> bool:\n    return not enabled or pp == 1","tryCatchPattern":null,"preventionTips":["Fit MoE models with TP/EP instead of PP when routing telemetry is required","Scope --enable-return-routed-experts to single-stage deployments only"],"tags":["moe","pipeline-parallelism","expert-routing","config"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}