{"record":{"id":"6aa4346c0e6f30b4","repo":"vllm-project/vllm","slug":"enable-return-routed-experts-is-incompatible-wit-6aa434","errorCode":null,"errorMessage":"--enable-return-routed-experts is incompatible with KV connectors (PD disaggregation, KV cache offload).","messagePattern":"--enable-return-routed-experts is incompatible with KV connectors \\(PD disaggregation, KV cache offload\\)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/config/vllm.py","lineNumber":1095,"sourceCode":"            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\n        self._verify_sampling_replay_config()\n\n        if self.lora_config is not None:\n            self.lora_config.verify_with_model_config(self.model_config)\n\n        if (\n            self.mamba_config.enable_stochastic_rounding\n            and self.cache_config.mamba_ssm_cache_dtype != \"float16\"\n        ):\n            raise ValueError(\n                \"Stochastic rounding for Mamba cache requires \"\n                \"the SSM cache to be float16. Please set it explicitly, \"\n                \"by specifying `--mamba-ssm-cache-dtype float16`, or disable \"\n                \"stochastic rounding by not specifying \"","sourceCodeStart":1077,"sourceCodeEnd":1113,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/config/vllm.py#L1077-L1113","documentation":"The final routed-experts guard rejects any KV-transfer connector instance (kv_transfer_config.is_kv_transfer_instance). It covers both PD disaggregation (kv_producer/kv_consumer — routing captured on the prefill instance can't reach the decode instance that answers the request) and single-instance KV offload/sharing (kv_both — slot_mapping semantics change when KV blocks live outside local GPU memory, breaking the slot-indexed routed_experts buffer). The in-code comment documents both failure modes explicitly.","triggerScenarios":"Running --enable-return-routed-experts together with any --kv-transfer-config role (producer, consumer, or both), e.g. a P/D-disaggregated DeepSeek serving stack with routing telemetry enabled.","commonSituations":"Adding expert-routing observability to a disaggregated serving cluster (NIXL/Mooncake PD); KV-offload setups for sleep/wake memory management; assuming the flag is purely local and orthogonal to KV plumbing.","solutions":["Disable --enable-return-routed-experts on any instance with a kv_transfer_config role","Run a separate non-disaggregated replica without KV connectors for routing analysis","Dump router logits/expert ids offline from the model forward instead of using the request-path API"],"exampleFix":"# before\nvllm serve moe-model --enable-return-routed-experts \\\n  --kv-transfer-config '{\"kv_role\":\"kv_producer\", ...}'\n# after\nvllm serve moe-model --enable-return-routed-experts  # no kv-transfer-config","handlingStrategy":"validation","validationCode":"if model_config.enable_return_routed_experts:\n    assert kv_transfer_config is None or not kv_transfer_config.is_kv_transfer_instance, \\\n        \"routed-experts return incompatible with KV connectors\"","typeGuard":"def routed_experts_kv_ok(enabled: bool, kv_cfg) -> bool:\n    return not enabled or kv_cfg is None or not kv_cfg.is_kv_transfer_instance","tryCatchPattern":null,"preventionTips":["Never enable routed-experts return on P/D-disaggregated instances","Run routing analysis on standalone non-KV-connector replicas or via offline logit dumps"],"tags":["moe","expert-routing","kv-transfer","disaggregation"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}