vllm-project/vllm · error · ValueError

'mm_shm_cache_max_object_size_mb' should only be set when 'm

Error message

'mm_shm_cache_max_object_size_mb' should only be set when 'mm_processor_cache_type' is 'shm'.

What it means

A model-level validator on MultiModalConfig rejects any non-default value of mm_shm_cache_max_object_size_mb when mm_processor_cache_type is not 'shm'. The shared-memory object-size cap is only meaningful for the shm cache, so setting it alongside the default 'lru' cache is treated as a configuration mistake.

Source

Thrown at vllm/config/multimodal.py:314

                "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
        ):
            raise ValueError(
                "'mm_shm_cache_max_object_size_mb' should only be set when "
                "'mm_processor_cache_type' is 'shm'."
            )
        # Validate FP8 scale path combinations.
        if self.mm_encoder_attn_dtype != "fp8" and (
            self.mm_encoder_fp8_scale_path is not None
            or self.mm_encoder_fp8_scale_save_path is not None
        ):
            raise ValueError(
                "'mm_encoder_fp8_scale_path' and "
                "'mm_encoder_fp8_scale_save_path' require "
                "'mm_encoder_attn_dtype' to be 'fp8'."
            )
        if (
            self.mm_encoder_fp8_scale_path is not None
            and self.mm_encoder_fp8_scale_save_path is not None
        ):
            raise ValueError(

View on GitHub (pinned to c794754062)

Solutions

Add --mm-processor-cache-type shm if you genuinely want the shared-memory cache and its object-size cap.
Otherwise remove --mm-shm-cache-max-object-size-mb entirely and let it keep its default (128).

Example fix

# before
vllm serve Qwen/Qwen2.5-VL-7B --mm-shm-cache-max-object-size-mb 512

# after
vllm serve Qwen/Qwen2.5-VL-7B --mm-processor-cache-type shm --mm-shm-cache-max-object-size-mb 512

Defensive patterns

Strategy: validation

Validate before calling

DEFAULT_OBJ_MB = MultiModalConfig.mm_shm_cache_max_object_size_mb

def check_shm_opts(cache_type: str, max_obj_mb: int) -> None:
    if cache_type != "shm" and max_obj_mb != DEFAULT_OBJ_MB:
        raise SystemExit("mm_shm_cache_max_object_size_mb requires mm_processor_cache_type=shm")

Prevention

Treat --mm-shm-cache-max-object-size-mb as a sub-option of --mm-processor-cache-type shm; always set them together.
Wrap vLLM flag assembly in a config linter that enforces dependency rules before launch.

When it happens

Trigger: Passing --mm-shm-cache-max-object-size-warehouse values (e.g. 512) without also passing --mm-processor-cache-type shm; or programmatically MultiModalConfig(mm_shm_cache_max_object_size_mb=512) while cache_type stays at its default 'lru'.

Common situations: Tuning multimodal processor cache size after reading shm-cache docs but forgetting the enabling flag; merging YAML/JSON configs where cache_type was dropped; CI defaults changed so a previously-tolerated combo now validates.

Related errors

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