vllm-project/vllm · error · ValueError

offload_prefetch_step ({self.prefetch.offload_prefetch_step}

Error message

offload_prefetch_step ({self.prefetch.offload_prefetch_step}) must be >= 1 when prefetch offloading is enabled (offload_group_size > 0)

What it means

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.

Source

Thrown at vllm/config/offload.py:108

    uva: UVAOffloadConfig = Field(default_factory=UVAOffloadConfig)
    """Parameters for UVA offloading backend."""

    prefetch: PrefetchOffloadConfig = Field(default_factory=PrefetchOffloadConfig)
    """Parameters for prefetch offloading backend."""

    @model_validator(mode="after")
    def validate_offload_config(self) -> "OffloadConfig":
        """Validate offload configuration constraints."""
        if self.offload_backend == "prefetch" or self.prefetch.offload_group_size > 0:
            if self.prefetch.offload_num_in_group > self.prefetch.offload_group_size:
                raise ValueError(
                    f"offload_num_in_group ({self.prefetch.offload_num_in_group})"
                    f" must be <= offload_group_size"
                    f" ({self.prefetch.offload_group_size})"
                )
            if self.prefetch.offload_prefetch_step < 1:
                raise ValueError(
                    f"offload_prefetch_step"
                    f" ({self.prefetch.offload_prefetch_step})"
                    f" must be >= 1 when prefetch offloading is enabled"
                    f" (offload_group_size > 0)"
                )

        # Warn if both backends have non-default values
        uva_active = self.uva.cpu_offload_gb > 0
        prefetch_active = self.prefetch.offload_group_size > 0
        if self.offload_backend == "uva" and prefetch_active:
            warnings.warn(
                "Prefetch offload fields are set but offload_backend='uva'. "
                "Prefetch settings will be ignored.",
                stacklevel=2,
            )
        elif self.offload_backend == "prefetch" and uva_active:
            warnings.warn(
                "UVA offload fields are set but offload_backend='prefetch'. "

View on GitHub (pinned to c794754062)

Solutions

1. Set offload_prefetch_step to at least 1 (typical values are 1–4 steps ahead).
2. 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.

Example fix

# before
vllm serve model --offload-backend prefetch --offload-prefetch-step 0

# after
vllm serve model --offload-backend prefetch --offload-prefetch-step 1

def check_prefetch_step(step: int, group_size: int, backend: str) -> None:
    if (backend == "prefetch" or group_size > 0) and step < 1:
        raise SystemExit("offload_prefetch_step must be >= 1 when prefetch offloading is enabled")

When it happens

Trigger: Setting --offload-prefetch-step 0 (or a negative value) together with --offload-backend prefetch or any --offload-group-size > 0.

Common situations: 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'.

Related errors

• offload_num_in_group ({self.prefetch.offload_num_in_group})
• 'mm_shm_cache_max_object_size_mb' should only be set when 'm
• 'mm_encoder_fp8_scale_path' and 'mm_encoder_fp8_scale_save_p
• 'mm_encoder_fp8_scale_save_path' cannot be used with 'mm_enc
• Invalid "device" in mm_processor_kwargs: {device!r}. Expecte

AI-assisted analysis of vllm-project/vllm@c794754062 (2026-08-14). Data as JSON: /api/errors/73154bc6b02214fb. Report an issue: GitHub.