{"record":{"id":"9e0423507b07f435","repo":"vllm-project/vllm","slug":"prefill-context-parallelism-requires-model-runner","errorCode":null,"errorMessage":"Prefill context parallelism requires Model Runner V2. Remove VLLM_USE_V2_MODEL_RUNNER=0.","messagePattern":"Prefill context parallelism requires Model Runner V2\\. Remove VLLM_USE_V2_MODEL_RUNNER=0\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/config/vllm.py","lineNumber":1603,"sourceCode":"            and self.kv_events_config.publisher != \"null\"\n            and not self.kv_events_config.enable_kv_cache_events\n        ):\n            logger.warning_once(\n                \"KV cache events are disabled, \"\n                \"but the scheduler is configured to publish them. \"\n                \"Modify KVEventsConfig.enable_kv_cache_events \"\n                \"to True to enable.\"\n            )\n        current_platform.check_and_update_config(self)\n\n        self._resolve_mm_embeds_from_ec_connector()\n        self._resolve_mm_processor_device()\n        self._validate_mm_processor_device()\n\n        if self.use_v2_model_runner:\n            self._validate_v2_model_runner()\n        elif self.parallel_config.prefill_context_parallel_size > 1:\n            raise ValueError(\n                \"Prefill context parallelism requires Model Runner V2. \"\n                \"Remove VLLM_USE_V2_MODEL_RUNNER=0.\"\n            )\n\n        # Re-compute compile ranges after platform-specific config updates\n        # (e.g., XPU may lower max_num_batched_tokens when MLA is enabled)\n        self._set_compile_ranges()\n\n        # Do this after all the updates to compilation_config.mode\n        effective_dp_size = (\n            self.parallel_config.data_parallel_size\n            if self.model_config is None or self.model_config.is_moe\n            else 1\n        )\n        self.compilation_config.set_splitting_ops_for_v1(\n            all2all_backend=self.parallel_config.all2all_backend,\n            data_parallel_size=effective_dp_size,\n        )","sourceCodeStart":1585,"sourceCodeEnd":1621,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/config/vllm.py#L1585-L1621","documentation":"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.","triggerScenarios":"Launching with `--prefill-context-parallel-size N` (N>1) while `VLLM_USE_V2_MODEL_RUNNER=0` is exported in the environment.","commonSituations":"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.","solutions":["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.","Or set `prefill_context_parallel_size` back to 1 if the legacy runner is required.","Check container/service definitions (Dockerfile ENV, k8s manifests) for a stale VLLM_USE_V2_MODEL_RUNNER=0."],"exampleFix":"# before\nexport VLLM_USE_V2_MODEL_RUNNER=0\nvllm serve model --prefill-context-parallel-size 2\n\n# after\nunset VLLM_USE_V2_MODEL_RUNNER\nvllm serve model --prefill-context-parallel-size 2","handlingStrategy":"validation","validationCode":"import os\nif prefill_context_parallel_size > 1 and os.environ.get(\"VLLM_USE_V2_MODEL_RUNNER\") == \"0\":\n    del os.environ[\"VLLM_USE_V2_MODEL_RUNNER\"]","typeGuard":null,"tryCatchPattern":"try:\n    LLM(**args)\nexcept ValueError as e:\n    if \"requires Model Runner V2\" in str(e) and os.environ.pop(\"VLLM_USE_V2_MODEL_RUNNER\", None):\n        LLM(**args)\n    else:\n        raise","preventionTips":["Audit stale VLLM_* env overrides when adopting new parallelism features","Keep env-var workarounds dated and removable"],"tags":["context-parallelism","model-runner","environment"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}