vllm-project/vllm · error · ValueError

Unknown KV cache group kind '{kind}' in backend_per_kind. Va

Error message

Unknown KV cache group kind '{kind}' in backend_per_kind. Valid kinds are: {', '.join(sorted(valid_kinds))}.

What it means

The compilation config accepts a backend_per_kind mapping from KV cache group kind to attention backend enum. Keys are validated against KVCacheSpecKind values (e.g. 'full_attention', 'sliding_window', ...); an unknown key string raises ValueError listing the valid kinds.

Source

Thrown at vllm/config/attention.py:169

        return value

    @field_validator("backend_per_kind", mode="before")
    @classmethod
    def validate_backend_per_kind_before(cls, value: Any) -> Any:
        """Parse the `backend_per_kind` map from strings.

        Keys must be valid `KVCacheSpecKind` values; values are parsed like
        `backend` (enum name, case-insensitive).
        """
        from vllm.v1.kv_cache_interface import KVCacheSpecKind

        if not isinstance(value, dict):
            return value
        valid_kinds = {kind.value for kind in KVCacheSpecKind}
        parsed: dict[str, AttentionBackendEnum] = {}
        for kind, backend in value.items():
            if kind not in valid_kinds:
                raise ValueError(
                    f"Unknown KV cache group kind '{kind}' in "
                    f"backend_per_kind. Valid kinds are: "
                    f"{', '.join(sorted(valid_kinds))}."
                )
            if isinstance(backend, str):
                backend = AttentionBackendEnum[backend.upper()]
            parsed[kind] = backend
        return parsed

View on GitHub (pinned to c794754062)

Solutions

Use one of the valid kinds listed in the error message, e.g. {'full_attention': 'FLASHINFER', 'sliding_window': 'XFORMERS'}.
Check KVCacheSpecKind in vllm.v1.kv_cache_interface for your vLLM version to see supported kinds.
Ensure backend values are attention backend enum names (case-insensitive), not kinds.

Example fix

# before
CompilationConfig(backend_per_kind={'full': 'FLASHATTN'})
# after
from vllm.v1.kv_cache_interface import KVCacheSpecKind
CompilationConfig(backend_per_kind={KVCacheSpecKind.FULL_ATTENTION.value: 'FLASHATTN'})

Defensive patterns

Strategy: type-guard

Validate before calling

from vllm.v1.kv_cache_interface import KVCacheSpecKind

def valid_backend_per_kind(cfg: dict) -> bool:
    valid = {k.value for k in KVCacheSpecKind}
    return set(cfg.keys()) <= valid

Type guard

def is_valid_kind_map(value: dict) -> bool:
    valid = {k.value for k in KVCacheSpecKind}
    return isinstance(value, dict) and set(value) <= valid

Prevention

Derive kind names from KVCacheSpecKind members, never hardcode strings
Validate config dicts against the enum before constructing CompilationConfig
Re-check valid kinds after vLLM upgrades

When it happens

Trigger: Passing CompilationConfig(attention_backend_cfg / backend_per_kind={'foo': 'FLASHATTN'}) — any dict key that is not a member of KVCacheSpecKind — during config parsing (the mode='before' validator).

Common situations: Typos in kind names; using attention-backend names or model names instead of KV cache group kinds; configs written for a newer/older vLLM whose KVCacheSpecKind members differ.

Related errors

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