vllm-project/vllm · error · ValueError

compile_cache_save_format must be 'binary' or 'unpacked'…

Error message

compile_cache_save_format must be 'binary' or 'unpacked', got: {value}

What it means

CompilationConfig.compile_cache_save_format controls how compiled artifacts are persisted; only 'binary' (packed compiled cache) and 'unpacked' (json + so files) are implemented. Any other string fails the pydantic field validator with ValueError.

Solutions

1. Set compile_cache_save_format='binary' (default, single file) or 'unpacked' (directory of json + shared objects).
2. Omit the field to keep the default.
3. If you need a different format for artifact distribution, post-process the unpacked output yourself.

Example fix

# before
CompilationConfig(compile_cache_save_format='json')
# after
CompilationConfig(compile_cache_save_format='unpacked')

VALID = {'binary', 'unpacked'}
def valid_save_format(v: str) -> bool:
    return v in VALID

def is_valid_save_format(value) -> bool:
    return value in ('binary', 'unpacked')

When it happens

Trigger: Setting compilation_config=CompilationConfig(compile_cache_save_format='json') or 'safetensors' etc.; commonly set when preparing a shared/distributed compilation cache.

Common situations: Guessing format names; using configs written for other torch versions (e.g. torch inductor cache formats like 'inductor'); copy-paste from docs of a different tool.

Related errors

• Compilation mode cannot be NO_COMPILATION
• connected engine range
• data parallel size ( ) exceeds the two-byte engine identity…
• data parallel size must be at least 1
• engine count must be at least 1

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

Appendix: source

Thrown at vllm/config/compilation.py:884

    def validate_cudagraph_mode_before(cls, value: Any) -> Any:
        """Enable parsing of the `cudagraph_mode` enum type from string."""
        if isinstance(value, str):
            return CUDAGraphMode[value.upper()]
        return value

    @field_validator("pass_config", mode="before")
    @classmethod
    def validate_pass_config_before(cls, value: Any) -> Any:
        """Enable parsing of the `pass_config` field from a dictionary."""
        if isinstance(value, dict):
            return PassConfig(**value)
        return value

    @field_validator("compile_cache_save_format")
    @classmethod
    def validate_compile_cache_save_format(cls, value: str) -> str:
        if value not in ("binary", "unpacked"):
            raise ValueError(
                f"compile_cache_save_format must be 'binary' or 'unpacked', "
                f"got: {value}"
            )
        return value

    @field_validator(
        "level",
        "mode",
        "cudagraph_mode",
        "max_cudagraph_capture_size",
        "use_inductor_graph_partition",
        "ir_enable_torch_wrap",
        mode="wrap",
    )
    @classmethod
    def _skip_none_validation(cls, value: Any, handler: Callable) -> Any:
        """Skip validation if the value is `None` when initialisation is delayed."""
        if value is None:

View on GitHub (pinned to c794754062)