vllm-project/vllm · error · ValueError

Attention backend 'XFORMERS' has been removed (See PR #29262

Error message

Attention backend 'XFORMERS' has been removed (See PR #29262 for details). Please select a supported attention backend.

What it means

MultiModalConfig's field validator for mm_encoder_attn_backend rejects the string 'XFORMERS' (case-insensitive) before enum conversion. The XFORMERS attention backend was removed from vLLM in PR #29262, so any config or CLI that still names it fails fast at model-validation time instead of later at engine init.

Source

Thrown at vllm/config/multimodal.py:295

            # Convert to the appropriate DummyOptions subclass
            if k == "video":
                out[k] = VideoDummyOptions(**v)
            elif k == "image":
                out[k] = ImageDummyOptions(**v)
            elif k == "audio":
                out[k] = AudioDummyOptions(**v)
            else:
                out[k] = BaseDummyOptions(**v)

        return out

    @field_validator("mm_encoder_attn_backend", mode="before")
    @classmethod
    def _validate_mm_encoder_attn_backend(
        cls, value: str | AttentionBackendEnum | None
    ) -> AttentionBackendEnum | None:
        if isinstance(value, str) and value.upper() == "XFORMERS":
            raise ValueError(
                "Attention backend 'XFORMERS' has been removed (See PR #29262 for "
                "details). Please select a supported attention backend."
            )

        if value is None or isinstance(value, AttentionBackendEnum):
            return value

        assert isinstance(value, str), (
            "mm_encoder_attn_backend must be a string or an AttentionBackendEnum."
        )
        return AttentionBackendEnum[value.upper()]

    @model_validator(mode="after")
    def _validate_multimodal_config(self):
        if self.mm_processor_cache_type != "shm" and (
            self.mm_shm_cache_max_object_size_mb
            != MultiModalConfig.mm_shm_cache_max_object_size_mb
        ):

View on GitHub (pinned to c794754062)

Solutions

1. Remove or replace the flag with a supported backend from AttentionBackendEnum, e.g. --mm-encoder-attn-backend=flash_attn (FLASH_ATTN, TRITON_ATTN, TORCH_SDPA, FLASHINFER, ROCM_* variants are valid).
2. If you did not set the flag explicitly, search your scripts/env for stale VLLM_* variables or config files containing 'xformers'.
3. For ViT-style encoders, TORCH_SDPA or FLASH_ATTN is usually the drop-in replacement; verify with vllm.v1.attention.backends.registry.AttentionBackendEnum.__members__.

Example fix

# before
vllm serve meta-llama/Llama-3.2-11B-Vision --mm-encoder-attn-backend XFORMERS

# after
vllm serve meta-llama/Llama-3.2-11B-Vision --mm-encoder-attn-backend FLASH_ATTN

from vllm.v1.attention.backends.registry import AttentionBackendEnum

def validate_mm_attn_backend(name: str) -> str:
    if name.upper() == "XFORMERS":
        raise SystemExit("XFORMERS backend was removed (PR #29262); use FLASH_ATTN/TRITON_ATTN/TORCH_SDPA etc.")
    if name.upper() not in AttentionBackendEnum.__members__:
        raise SystemExit(f"Unknown backend {name}; valid: {list(AttentionBackendEnum.__members__)}")
    return name

def is_supported_backend(name: str) -> bool:
    return name.upper() in AttentionBackendEnum.__members__

try:
    MultiModalConfig(mm_encoder_attn_backend=name)
except ValueError as e:
    if "XFORMERS" in str(e):
        name = "FLASH_ATTN"  # explicit migration decision, then retry
    else:
        raise

When it happens

Trigger: Setting --mm-encoder-attn-backend=xformers (any casing) or passing MultiModalConfig(mm_encoder_attn_backend="XFORMERS") / EngineArgs with that value; typically for multimodal encoder (ViT) attention on older launch scripts.

Common situations: Upgrading vLLM to a version that includes PR #29262 while reusing old launch commands, Helm charts, or docker entrypoints that hardcoded xformers; copying tutorials or configs written for vLLM <= 0.9.x.

Related errors

• '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
• FP8 scale file not found: {scale_path}
• Parent directory for FP8 scale save path not found: {save_pa

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