sgl-project/sglang · error · ValueError

mm_preprocess_cache_size_mb must be non-negative

Error message

mm_preprocess_cache_size_mb must be non-negative

What it means

The multimodal preprocessing cache size (--mm-preprocess-cache-size-mb) must be None (unset) or a non-negative number. SGLang validates this in _handle_multimodal before workers start, because a negative cache size is meaningless.

Source

Thrown at python/sglang/srt/server_args.py:4377

                    "--enable-http2 requires the 'granian' package. "
                    'Install it with: pip install "sglang[http2]"'
                )

            if cfg.enable_ssl_refresh:
                raise ValueError(
                    "--enable-ssl-refresh is not supported with --enable-http2. "
                    "Granian does not support SSL certificate hot-reloading. "
                    "Use Uvicorn (the default) or handle certificate rotation externally."
                )

    def _handle_multimodal(self):
        """Validate mm_process_config structure before model loading."""
        cfg = resolving_view(self)
        if (
            cfg.mm_preprocess_cache_size_mb is not None
            and cfg.mm_preprocess_cache_size_mb < 0
        ):
            raise ValueError("mm_preprocess_cache_size_mb must be non-negative")
        if cfg.mm_process_config is not None:
            if not isinstance(cfg.mm_process_config, dict):
                raise TypeError(
                    f"mm_process_config must be a dict, "
                    f"but got {type(cfg.mm_process_config)}"
                )
            for key in ("image", "video", "audio"):
                if key in cfg.mm_process_config and not isinstance(
                    cfg.mm_process_config[key], dict
                ):
                    raise TypeError(
                        f"mm_process_config['{key}'] must be a dict, "
                        f"but got {type(cfg.mm_process_config[key])}"
                    )

    def _handle_media_url_security(self):
        """Normalize and publish the media URL policy before workers start."""
        cfg = resolving_view(self)

View on GitHub (pinned to 0132848349)

Solutions

1. Pass a non-negative value, e.g. --mm-preprocess-cache-size-mb 512
2. To effectively disable caching, set it to 0 (if supported) or omit the flag
3. Check env/launch scripts for accidental negative values

Example fix

# before
--mm-preprocess-cache-size-mb -1
# after
--mm-preprocess-cache-size-mb 0

if args.mm_preprocess_cache_size_mb is not None:
    assert args.mm_preprocess_cache_size_mb >= 0

When it happens

Trigger: Passing --mm-preprocess-cache-size-mb -1 or any negative value (or a negative SGLANG_* env override) at server launch.

Common situations: Attempting to disable the cache with -1 or 0 semantics borrowed from other tools; sign typos in tuning scripts; env var overrides with stray minus signs.

Related errors

• Invalid modality '{modality}' in --limit-mm-data-per-request
• Z-Image text embeddings must have shape [seq, dim] or [batch
• f"Unsupported patch_size type: {type(patch_size)}"
• f"Expected camera embedding shape [B, C, F, H, W], got {tupl
• batching config rule requires max_batch_size

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/e716cf8a62de6e14. Report an issue: GitHub.