{"record":{"id":"ef6348a719053ff0","repo":"vllm-project/vllm","slug":"attention-backend-xformers-has-been-removed-see","errorCode":null,"errorMessage":"Attention backend 'XFORMERS' has been removed (See PR #29262 for details). Please select a supported attention backend.","messagePattern":"Attention backend 'XFORMERS' has been removed \\(See PR #29262 for details\\)\\. Please select a supported attention backend\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/config/multimodal.py","lineNumber":295,"sourceCode":"            # Convert to the appropriate DummyOptions subclass\n            if k == \"video\":\n                out[k] = VideoDummyOptions(**v)\n            elif k == \"image\":\n                out[k] = ImageDummyOptions(**v)\n            elif k == \"audio\":\n                out[k] = AudioDummyOptions(**v)\n            else:\n                out[k] = BaseDummyOptions(**v)\n\n        return out\n\n    @field_validator(\"mm_encoder_attn_backend\", mode=\"before\")\n    @classmethod\n    def _validate_mm_encoder_attn_backend(\n        cls, value: str | AttentionBackendEnum | None\n    ) -> AttentionBackendEnum | None:\n        if isinstance(value, str) and value.upper() == \"XFORMERS\":\n            raise ValueError(\n                \"Attention backend 'XFORMERS' has been removed (See PR #29262 for \"\n                \"details). Please select a supported attention backend.\"\n            )\n\n        if value is None or isinstance(value, AttentionBackendEnum):\n            return value\n\n        assert isinstance(value, str), (\n            \"mm_encoder_attn_backend must be a string or an AttentionBackendEnum.\"\n        )\n        return AttentionBackendEnum[value.upper()]\n\n    @model_validator(mode=\"after\")\n    def _validate_multimodal_config(self):\n        if self.mm_processor_cache_type != \"shm\" and (\n            self.mm_shm_cache_max_object_size_mb\n            != MultiModalConfig.mm_shm_cache_max_object_size_mb\n        ):","sourceCodeStart":277,"sourceCodeEnd":313,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/config/multimodal.py#L277-L313","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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).","If you did not set the flag explicitly, search your scripts/env for stale VLLM_* variables or config files containing 'xformers'.","For ViT-style encoders, TORCH_SDPA or FLASH_ATTN is usually the drop-in replacement; verify with vllm.v1.attention.backends.registry.AttentionBackendEnum.__members__."],"exampleFix":"# before\nvllm serve meta-llama/Llama-3.2-11B-Vision --mm-encoder-attn-backend XFORMERS\n\n# after\nvllm serve meta-llama/Llama-3.2-11B-Vision --mm-encoder-attn-backend FLASH_ATTN","handlingStrategy":"validation","validationCode":"from vllm.v1.attention.backends.registry import AttentionBackendEnum\n\ndef validate_mm_attn_backend(name: str) -> str:\n    if name.upper() == \"XFORMERS\":\n        raise SystemExit(\"XFORMERS backend was removed (PR #29262); use FLASH_ATTN/TRITON_ATTN/TORCH_SDPA etc.\")\n    if name.upper() not in AttentionBackendEnum.__members__:\n        raise SystemExit(f\"Unknown backend {name}; valid: {list(AttentionBackendEnum.__members__)}\")\n    return name","typeGuard":"def is_supported_backend(name: str) -> bool:\n    return name.upper() in AttentionBackendEnum.__members__","tryCatchPattern":"try:\n    MultiModalConfig(mm_encoder_attn_backend=name)\nexcept ValueError as e:\n    if \"XFORMERS\" in str(e):\n        name = \"FLASH_ATTN\"  # explicit migration decision, then retry\n    else:\n        raise","preventionTips":["Keep backend names in one config constant instead of scattering literals across scripts.","After a vLLM upgrade, grep launch scripts for removed-backend names (xformers).","Enumerate AttentionBackendEnum.__members__ to pick a valid backend at startup."],"tags":["vllm","config","attention-backend","multimodal","migration"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}