{"record":{"id":"73154bc6b02214fb","repo":"vllm-project/vllm","slug":"offload-prefetch-step-self-prefetch-offload-pref","errorCode":null,"errorMessage":"offload_prefetch_step ({self.prefetch.offload_prefetch_step}) must be >= 1 when prefetch offloading is enabled (offload_group_size > 0)","messagePattern":"offload_prefetch_step \\((.+?)\\) must be >= 1 when prefetch offloading is enabled \\(offload_group_size > 0\\)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/config/offload.py","lineNumber":108,"sourceCode":"\n    uva: UVAOffloadConfig = Field(default_factory=UVAOffloadConfig)\n    \"\"\"Parameters for UVA offloading backend.\"\"\"\n\n    prefetch: PrefetchOffloadConfig = Field(default_factory=PrefetchOffloadConfig)\n    \"\"\"Parameters for prefetch offloading backend.\"\"\"\n\n    @model_validator(mode=\"after\")\n    def validate_offload_config(self) -> \"OffloadConfig\":\n        \"\"\"Validate offload configuration constraints.\"\"\"\n        if self.offload_backend == \"prefetch\" or self.prefetch.offload_group_size > 0:\n            if self.prefetch.offload_num_in_group > self.prefetch.offload_group_size:\n                raise ValueError(\n                    f\"offload_num_in_group ({self.prefetch.offload_num_in_group})\"\n                    f\" must be <= offload_group_size\"\n                    f\" ({self.prefetch.offload_group_size})\"\n                )\n            if self.prefetch.offload_prefetch_step < 1:\n                raise ValueError(\n                    f\"offload_prefetch_step\"\n                    f\" ({self.prefetch.offload_prefetch_step})\"\n                    f\" must be >= 1 when prefetch offloading is enabled\"\n                    f\" (offload_group_size > 0)\"\n                )\n\n        # Warn if both backends have non-default values\n        uva_active = self.uva.cpu_offload_gb > 0\n        prefetch_active = self.prefetch.offload_group_size > 0\n        if self.offload_backend == \"uva\" and prefetch_active:\n            warnings.warn(\n                \"Prefetch offload fields are set but offload_backend='uva'. \"\n                \"Prefetch settings will be ignored.\",\n                stacklevel=2,\n            )\n        elif self.offload_backend == \"prefetch\" and uva_active:\n            warnings.warn(\n                \"UVA offload fields are set but offload_backend='prefetch'. \"","sourceCodeStart":90,"sourceCodeEnd":126,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/config/offload.py#L90-L126","documentation":"The same OffloadConfig validator requires offload_prefetch_step >= 1 whenever prefetch offloading is active (backend 'prefetch' or offload_group_size > 0). A prefetch step of 0 or negative would mean 'prefetch nothing / look backwards', which the prefetcher cannot do, so it is rejected.","triggerScenarios":"Setting --offload-prefetch-step 0 (or a negative value) together with --offload-backend prefetch or any --offload-group-size > 0.","commonSituations":"Trying to disable prefetching while keeping the prefetch offload backend, instead of switching to the 'uva' backend or disabling offload; treating 0 as 'auto/default'.","solutions":["Set offload_prefetch_step to at least 1 (typical values are 1–4 steps ahead).","If the intent was to disable prefetching entirely, use a different offload_backend (e.g. 'uva') or turn offloading off rather than zeroing the step."],"exampleFix":"# before\nvllm serve model --offload-backend prefetch --offload-prefetch-step 0\n\n# after\nvllm serve model --offload-backend prefetch --offload-prefetch-step 1","handlingStrategy":"validation","validationCode":"def check_prefetch_step(step: int, group_size: int, backend: str) -> None:\n    if (backend == \"prefetch\" or group_size > 0) and step < 1:\n        raise SystemExit(\"offload_prefetch_step must be >= 1 when prefetch offloading is enabled\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Never use 0 to 'disable' prefetching — switch backends or disable offload instead.","Keep prefetch step within 1–4; larger values waste prefetch bandwidth."],"tags":["vllm","config","offloading","prefetch","validation"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}