{"record":{"id":"a9b048cc956c06b9","repo":"vllm-project/vllm","slug":"customized-max-cudagraph-capture-size-self-compi","errorCode":null,"errorMessage":"customized max_cudagraph_capture_size(={self.compilation_config.max_cudagraph_capture_size}) should be consistent with the max value of cudagraph_capture_sizes(={valid_max_size})","messagePattern":"customized max_cudagraph_capture_size\\(=(.+?)\\) should be consistent with the max value of cudagraph_capture_sizes\\(=(.+?)\\)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/config/vllm.py","lineNumber":2015,"sourceCode":"                and self.compilation_config.pass_config.enable_sp\n            ):\n                cudagraph_capture_sizes = self.update_sizes_for_sequence_parallelism(\n                    cudagraph_capture_sizes\n                )\n\n            # user-specific compilation_config.max_cudagraph_capture_size get\n            # truncated to valid_max_size when they are inconsistent.\n            valid_max_size = (\n                cudagraph_capture_sizes[-1] if cudagraph_capture_sizes else 0\n            )\n            if (\n                self.compilation_config.max_cudagraph_capture_size is not None\n                and self.compilation_config.max_cudagraph_capture_size != valid_max_size\n            ):\n                # raise error only when both two flags are user-specified\n                # and they are inconsistent with each other\n                if self.compilation_config.cudagraph_capture_sizes is not None:\n                    raise ValueError(\n                        \"customized max_cudagraph_capture_size\"\n                        f\"(={self.compilation_config.max_cudagraph_capture_size}) \"\n                        \"should be consistent with the max value of \"\n                        f\"cudagraph_capture_sizes(={valid_max_size})\"\n                    )\n\n                logger.warning(\n                    \"Truncating max_cudagraph_capture_size to %d\",\n                    valid_max_size,\n                )\n            # always set the final max_cudagraph_capture_size\n            self.compilation_config.max_cudagraph_capture_size = valid_max_size\n\n            if self.compilation_config.cudagraph_capture_sizes is not None and len(\n                cudagraph_capture_sizes\n            ) < len(self.compilation_config.cudagraph_capture_sizes):\n                # If users have specified capture sizes, we only need to\n                # compare the lens before and after modification since the modified","sourceCodeStart":1997,"sourceCodeEnd":2033,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/config/vllm.py#L1997-L2033","documentation":"In `_set_cudagraph_sizes`, vLLM truncates `max_cudagraph_capture_size` to the largest entry of `cudagraph_capture_sizes` when only one is given. If BOTH `--compilation-config.max_cudagraph_capture_size` and an explicit `cudagraph_capture_sizes` list are set and their maxima disagree, it is treated as a user error rather than silently truncating.","triggerScenarios":"Passing both `max_cudagraph_capture_size` and a `cudagraph_capture_sizes` list via --compilation-config whose maximum element differs from max_cudagraph_capture_size.","commonSituations":"Fine-tuning CUDA graph capture ranges (e.g. capping graph size for memory) and specifying the full sizes list plus the max separately, with one number off by a power of two.","solutions":["Make max_cudagraph_capture_size equal to the last (max) entry of your cudagraph_capture_sizes list.","Or specify only one of the two options — set only cudagraph_capture_sizes, or only max_cudagraph_capture_size and let vLLM truncate."],"exampleFix":"# before\n--compilation-config '{\"max_cudagraph_capture_size\": 128,\n                     \"cudagraph_capture_sizes\": [1,2,4,8,16,32,64]}'\n\n# after\n--compilation-config '{\"max_cudagraph_capture_size\": 64,\n                     \"cudagraph_capture_sizes\": [1,2,4,8,16,32,64]}'","handlingStrategy":"validation","validationCode":"cc = {\"cudagraph_capture_sizes\": sizes} if sizes else {\"max_cudagraph_capture_size\": mx}\n# never set both; or enforce consistency:\nassert \"max_cudagraph_capture_size\" not in cc or cc[\"max_cudagraph_capture_size\"] == max(cc[\"cudagraph_capture_sizes\"])","typeGuard":null,"tryCatchPattern":"try:\n    LLM(compilation_config=cc, ...)\nexcept ValueError as e:\n    if \"max_cudagraph_capture_size\" in str(e):\n        cc.pop(\"max_cudagraph_capture_size\", None)  # let sizes list drive it\n    else:\n        raise","preventionTips":["Set either the sizes list or the max, not both","Derive max programmatically as max(sizes) to avoid drift"],"tags":["cuda-graphs","compilation-config","startup-config"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}