vllm-project/vllm · error · ValueError

--enable-return-routed-experts is incompatible with context

Error message

--enable-return-routed-experts is incompatible with context parallelism (DCP > 1 or PCP > 1).

What it means

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.

Source

Thrown at vllm/config/vllm.py:1081

            self.model_config.verify_with_parallel_config(self.parallel_config)
            self.model_config.verify_dual_chunk_attention_config(self.load_config)

            self.parallel_config.is_moe_model = self.model_config.is_moe

        if (
            self.model_config is not None
            and self.model_config.enable_return_routed_experts
        ):
            if self.parallel_config.pipeline_parallel_size > 1:
                raise ValueError(
                    "--enable-return-routed-experts is incompatible with "
                    "pipeline parallelism (PP > 1)."
                )
            if (
                self.parallel_config.decode_context_parallel_size > 1
                or self.parallel_config.prefill_context_parallel_size > 1
            ):
                raise ValueError(
                    "--enable-return-routed-experts is incompatible with context "
                    "parallelism (DCP > 1 or PCP > 1)."
                )

            # Incompatible with any KV connector — covers both PD disaggregation
            # (kv_producer/kv_consumer: routing captured on P can't reach D) 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).
            if (
                self.kv_transfer_config is not None
                and self.kv_transfer_config.is_kv_transfer_instance
            ):
                raise ValueError(
                    "--enable-return-routed-experts is incompatible with KV "
                    "connectors (PD disaggregation, KV cache offload)."
                )

View on GitHub (pinned to c794754062)

Solutions

1. Set decode_context_parallel_size=1 and prefill_context_parallel_size=1 (drop context parallelism) for the instance returning routed experts
2. Disable --enable-return-routed-experts on CP deployments and gather routing from a dedicated non-CP replica
3. Collect routing offline via router-logit dumps instead of the request-path API

Example fix

# before
vllm serve moe-model --enable-return-routed-experts --decode-context-parallel-size 4
# after
vllm serve moe-model --enable-return-routed-experts  # CP disabled

if model_config.enable_return_routed_experts:
    p = parallel_config
    assert p.decode_context_parallel_size <= 1 and p.prefill_context_parallel_size <= 1, \
        "routed-experts return incompatible with context parallelism"

def routed_experts_cp_ok(enabled: bool, dcp: int, pcp: int) -> bool:
    return not enabled or (dcp <= 1 and pcp <= 1)

When it happens

Trigger: Serving long-context workloads with --decode-context-parallel-size or --prefill-context-parallel-size greater than 1 while --enable-return-routed-experts is set.

Common situations: 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.

Related errors

• --enable-return-routed-experts is incompatible with pipeline
• Number of experts in the model must be greater than 0 when e
• Async EPLB is only supported with the default policy.
• {self.communicator} communicator is incompatible with async
• MLA DSpark does not currently support decode context paralle

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