vllm-project/vllm · error · ValueError

Prefill context parallelism requires Model Runner V2. Remove

Error message

Prefill context parallelism requires Model Runner V2. Remove VLLM_USE_V2_MODEL_RUNNER=0.

What it means

Prefill context parallelism (`prefill_context_parallel_size > 1`) is implemented only on top of the V2 model runner. Setting the environment variable `VLLM_USE_V2_MODEL_RUNNER=0` forces the legacy runner, and validation raises telling you to remove it.

Source

Thrown at vllm/config/vllm.py:1603

            and self.kv_events_config.publisher != "null"
            and not self.kv_events_config.enable_kv_cache_events
        ):
            logger.warning_once(
                "KV cache events are disabled, "
                "but the scheduler is configured to publish them. "
                "Modify KVEventsConfig.enable_kv_cache_events "
                "to True to enable."
            )
        current_platform.check_and_update_config(self)

        self._resolve_mm_embeds_from_ec_connector()
        self._resolve_mm_processor_device()
        self._validate_mm_processor_device()

        if self.use_v2_model_runner:
            self._validate_v2_model_runner()
        elif self.parallel_config.prefill_context_parallel_size > 1:
            raise ValueError(
                "Prefill context parallelism requires Model Runner V2. "
                "Remove VLLM_USE_V2_MODEL_RUNNER=0."
            )

        # Re-compute compile ranges after platform-specific config updates
        # (e.g., XPU may lower max_num_batched_tokens when MLA is enabled)
        self._set_compile_ranges()

        # Do this after all the updates to compilation_config.mode
        effective_dp_size = (
            self.parallel_config.data_parallel_size
            if self.model_config is None or self.model_config.is_moe
            else 1
        )
        self.compilation_config.set_splitting_ops_for_v1(
            all2all_backend=self.parallel_config.all2all_backend,
            data_parallel_size=effective_dp_size,
        )

View on GitHub (pinned to c794754062)

Solutions

1. Unset the variable: `unset VLLM_WORKER_MULTIPROC_METHOD 2>/dev/null; unset VLLM_USE_V2_MODEL_RUNNER` (specifically `unset VLLM_USE_V2_MODEL_RUNNER`) before launch.
2. Or set `prefill_context_parallel_size` back to 1 if the legacy runner is required.
3. Check container/service definitions (Dockerfile ENV, k8s manifests) for a stale VLLM_USE_V2_MODEL_RUNNER=0.

Example fix

# before
export VLLM_USE_V2_MODEL_RUNNER=0
vllm serve model --prefill-context-parallel-size 2

# after
unset VLLM_USE_V2_MODEL_RUNNER
vllm serve model --prefill-context-parallel-size 2

import os
if prefill_context_parallel_size > 1 and os.environ.get("VLLM_USE_V2_MODEL_RUNNER") == "0":
    del os.environ["VLLM_USE_V2_MODEL_RUNNER"]

try:
    LLM(**args)
except ValueError as e:
    if "requires Model Runner V2" in str(e) and os.environ.pop("VLLM_USE_V2_MODEL_RUNNER", None):
        LLM(**args)
    else:
        raise

When it happens

Trigger: Launching with `--prefill-context-parallel-size N` (N>1) while `VLLM_USE_V2_MODEL_RUNNER=0` is exported in the environment.

Common situations: Reusing an old workaround env block (VLLM_USE_V2_MODEL_RUNNER=0 was set to dodge an earlier V2 bug) while trying new long-prefill context parallelism features.

Related errors

• Model Runner V2 requires Triton.
• failed to parse `RUST_LOG`
• Could not determine Python executable. Please provide it man
• The `_qutlass_C` extension is not loaded. Make sure your cus
• Could not collect pip list output (pip or uv module not avai

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