{"record":{"id":"3030928d232b3fb3","repo":"vllm-project/vllm","slug":"model-runner-v2-requires-triton","errorCode":null,"errorMessage":"Model Runner V2 requires Triton.","messagePattern":"Model Runner V2 requires Triton\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/config/vllm.py","lineNumber":2482,"sourceCode":"\n        if model_config is not None and (\n            model_config.logits_processors or has_logitsproc_plugins\n        ):\n            unsupported.append(\"custom logits processors\")\n\n        if model_config is not None and model_config.enable_prompt_embeds:\n            unsupported.append(\"prompt embeds\")\n\n        if self.cache_config.kv_sharing_fast_prefill:\n            # Will be added by https://github.com/vllm-project/vllm/pull/35045\n            unsupported.append(\"KV sharing fast prefill\")\n\n        return unsupported\n\n    def _validate_v2_model_runner(self) -> None:\n        \"\"\"Check for features not yet supported by the V2 model runner.\"\"\"\n        if not HAS_TRITON:\n            raise ValueError(\"Model Runner V2 requires Triton.\")\n\n        unsupported = self._get_v2_model_runner_unsupported_features()\n        if unsupported:\n            raise ValueError(\n                f\"Model Runner V2 does not yet support: {', '.join(unsupported)}\"\n            )\n\n    def validate_block_size(self) -> None:\n        \"\"\"Validate block_size against DCP and mamba constraints.\n\n        Called after Platform.update_block_size_for_backend() has\n        finalised block_size.\n        \"\"\"\n        block_size = self.cache_config.block_size\n\n        # DCP interleave-size compatibility\n        if self.parallel_config.decode_context_parallel_size > 1:\n            if self.parallel_config.dcp_kv_cache_interleave_size > 1 and (","sourceCodeStart":2464,"sourceCodeEnd":2500,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/config/vllm.py#L2464-L2500","documentation":"The V2 model runner depends on Triton kernels (HAS_TRITON is False when the triton package is unavailable in the venv). `_validate_v2_model_runner` raises immediately if Triton is not importable, before any other V2 feature checks.","triggerScenarios":"Enabling the V2 model runner (via VLLM_USE_V2_MODEL_RUNNER=1 or defaulting to it) in an environment where the `triton` package failed to install or import.","commonSituations":"Minimal/CPU containers or custom builds where triton was skipped; broken triton installs after a torch upgrade; platform wheels without triton bundled.","solutions":["Install Triton into the environment: `uv pip install triton` (or reinstall vLLM so its triton dependency resolves).","Or fall back to the legacy runner by setting `VLLM_USE_V2_MODEL_RUNNER=0` (noting some features like prefill context parallelism then become unavailable).","Verify with `python -c \"import triton\"` before launching."],"exampleFix":"# before\npython -c \"import triton\"  # ModuleNotFoundError\nvllm serve model  # raises: Model Runner V2 requires Triton.\n\n# after\nuv pip install triton\npython -c \"import triton\"  # ok\nvllm serve model","handlingStrategy":"validation","validationCode":"try:\n    import triton  # noqa: F401\n    HAS_TRITON = True\nexcept ImportError:\n    HAS_TRITON = False\nif use_v2_model_runner and not HAS_TRITON:\n    raise SystemExit(\"install triton or set VLLM_USE_V2_MODEL_RUNNER=0\")","typeGuard":"def v2_runner_available() -> bool:\n    try:\n        import triton  # noqa: F401\n        return True\n    except ImportError:\n        return False","tryCatchPattern":"try:\n    LLM(**args)\nexcept ValueError as e:\n    if \"requires Triton\" in str(e):\n        os.environ[\"VLLM_USE_V2_MODEL_RUNNER\"] = \"0\"\n    else:\n        raise","preventionTips":["Verify `import triton` in deployment image build","Pin triton in the vLLM environment manifest"],"tags":["triton","model-runner","environment","dependencies"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}