vllm-project/vllm · error · ValueError

Invalid compilation mode: {value}. Valid modes are: {', '.jo

Error message

Invalid compilation mode: {value}. Valid modes are: {', '.join(CompilationMode.__members__.keys())}

What it means

CompilationConfig's mode field accepts either the integer enum value or a string name; strings are upper-cased and looked up in CompilationMode.__members__. A string that matches no member (NONE, STOCK_TORCH_COMPILE, DYNAMO_TRACE_ONCE, VLLM_COMPILE) raises ValueError listing valid names.

Source

Thrown at vllm/config/compilation.py:856

        return str(config)

    __str__ = __repr__

    @field_validator("mode", mode="before")
    @classmethod
    def validate_mode_before(cls, value: Any) -> Any:
        """
        Enable parsing the `mode` field from string mode names.
        Accepts both integers (0-3) and string names, like NONE, STOCK_TORCH_COMPILE,
        DYNAMO_TRACE_ONCE, VLLM_COMPILE.
        """
        if isinstance(value, str):
            # Convert string mode name to integer value
            mode_name = value.upper()

            if mode_name not in CompilationMode.__members__:
                raise ValueError(
                    f"Invalid compilation mode: {value}. "
                    f"Valid modes are: {', '.join(CompilationMode.__members__.keys())}"
                )

            return CompilationMode[mode_name]
        return value

    @field_validator("cudagraph_mode", mode="before")
    @classmethod
    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:

View on GitHub (pinned to c794754062)

Solutions

Use a valid mode name: 'NONE', 'STOCK_TORCH_COMPILE', 'DYNAMO_TRACE_ONCE', or 'VLLM_COMPILE'.
Or pass the integer enum value from vllm.config.compilation.CompilationMode.
For quick control, use the -O level flags (e.g. -O3 maps to VLLM_COMPILE) instead of raw mode strings.

Example fix

# before
CompilationConfig(mode='PIECEWISE')
# after
CompilationConfig(mode='VLLM_COMPILE')

Defensive patterns

Strategy: type-guard

Validate before calling

from vllm.config.compilation import CompilationMode

def valid_mode(value: str) -> bool:
    return value.upper() in CompilationMode.__members__

Type guard

from vllm.config.compilation import CompilationMode

def is_valid_compilation_mode(value) -> bool:
    if isinstance(value, CompilationMode):
        return True
    return isinstance(value, str) and value.upper() in CompilationMode.__members__

Prevention

Reference CompilationMode members instead of raw strings
Wrap user-provided mode strings in a validator before config construction
Use -O level flags for common cases

When it happens

Trigger: Passing compilation_config=CompilationConfig(mode='PIECEWISE') or any misspelled/outdated mode name from the CLI, env, or Python config.

Common situations: Configs ported from older vLLM where modes had different names (e.g. 'piecewise'); typos like 'vllm' or 'torch_compile'; lower-case names are fine since they are upper-cased, but wrong words are not.

Related errors

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