{"record":{"id":"f6b934336a7beb58","repo":"vllm-project/vllm","slug":"deepseek-v4-does-not-support-piecewise-cuda-graphs","errorCode":null,"errorMessage":"DeepSeek V4 does not support PIECEWISE CUDA graphs with Model Runner V1. Use Model Runner V2 or disable PIECEWISE CUDA graphs.","messagePattern":"DeepSeek V4 does not support PIECEWISE CUDA graphs with Model Runner V1\\. Use Model Runner V2 or disable PIECEWISE CUDA graphs\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/config/vllm.py","lineNumber":707,"sourceCode":"\n        if getattr(model_config, \"is_attention_free\", False):\n            return False\n        return is_default_v2_architecture or not model_config.is_moe\n\n    def _validate_mrv1_piecewise_cudagraph(self) -> None:\n        if self.use_v2_model_runner:\n            return\n        model_config = self.model_config\n        if model_config is None:\n            return\n        if not self.compilation_config.cudagraph_mode.has_piecewise_cudagraphs():\n            return\n        architectures = getattr(model_config, \"architectures\", [])\n        if any(\n            arch in MRV1_UNSUPPORTED_PIECEWISE_CUDAGRAPH_ARCHITECTURES\n            for arch in architectures\n        ):\n            raise ValueError(\n                \"DeepSeek V4 does not support PIECEWISE CUDA graphs with \"\n                \"Model Runner V1. Use Model Runner V2 or disable PIECEWISE \"\n                \"CUDA graphs.\"\n            )\n\n    @property\n    def needs_dp_coordinator(self) -> bool:\n        \"\"\"\n        Determine if the DPCoordinator process is needed.\n\n        The DPCoordinator is needed in two cases:\n        1. For MoE models with DP > 1: to handle wave coordination\n           (even in external LB mode, since wave coordination runs in the coordinator)\n        2. For non-MoE models in internal/hybrid LB mode: to collect and publish\n           queue stats for load balancing across DP ranks\n\n        Returns:\n            True if DPCoordinator process is needed, False otherwise.","sourceCodeStart":689,"sourceCodeEnd":725,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/config/vllm.py#L689-L725","documentation":"VllmConfig raises this when Model Runner V1 is active, the compilation config enables PIECEWISE CUDA graphs, and the model architecture is DeepseekV4ForCausalLM (the sole entry in MRV1_UNSUPPORTED_PIECEWISE_CUDAGRAPH_ARCHITECTURES). DeepSeek V4's piecewise-split graph is only implemented for the V2 model runner, so V1 + piecewise would crash at capture time; the config check fails fast instead. Note the guard is skipped entirely when use_v2_model_runner is true, when there is no model config, or when cudagraph_mode lacks piecewise graphs.","triggerScenarios":"Running DeepseekV4ForCausalLM with default Model Runner V1 while compilation_config.cudagraph_mode includes PIECEWISE (the default full+piecewise mode), e.g. vllm serve <deepseek-v4> without V2 flags or with enforce_eager disabling only full graphs.","commonSituations":"Loading a new DeepSeek V4 checkpoint on an older engine default (V1 runner); explicitly forcing V1 via config while keeping default cudagraph_mode; an environment where DEFAULT_V2_MODEL_RUNNER_ARCHITECTURES was not applied (force-v1 overrides).","solutions":["Enable Model Runner V2 (e.g. set the V2 model runner flag / VLLM_USE_V2_MODEL_RUNNER or the config that sets use_v2_model_runner) for DeepSeek V4","Or disable piecewise CUDA graphs: set cudagraph_mode to FULL/NONE (e.g. --compilation-config '{\"cudagraph_mode\": \"FULL\"}') or run with enforce_eager","Upgrade vLLM so DeepSeek V4 defaults to the V2 runner (it is listed in DEFAULT_V2_MODEL_RUNNER_ARCHITECTURES)"],"exampleFix":"# before\nvllm serve deepseek-ai/DeepSeek-V4 --use-v1-model-runner\n# after\nvllm serve deepseek-ai/DeepSeek-V4  # V2 model runner is the default for this arch\n# or: --compilation-config '{\"cudagraph_mode\": \"FULL\"}'","handlingStrategy":"validation","validationCode":"arch = model_config.architectures[0] if model_config.architectures else \"\"\nif arch == \"DeepseekV4ForCausalLM\":\n    assert use_v2_model_runner or not compilation_config.cudagraph_mode.has_piecewise_cudagraphs(), \\\n        \"DeepSeek V4 + MRV1 requires disabling piecewise cudagraphs\"","typeGuard":"def deepseek_v4_runner_ok(arch: str, use_v2: bool, piecewise: bool) -> bool:\n    return use_v2 or arch != \"DeepseekV4ForCausalLM\" or not piecewise","tryCatchPattern":null,"preventionTips":["Keep DeepSeek V4 deployments on current vLLM where V2 runner is default for that arch","When forcing Model Runner V1, audit cudagraph_mode in compilation_config","Watch the DEFAULT_V2_MODEL_RUNNER_ARCHITECTURES list when adopting new model families"],"tags":["cuda-graph","deepseek","model-runner","config"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}