vllm - 💡(How to fix) Fix [Bug]: --hash-block-size 0 silently passes validation, crashes resolve_kv_cache_block_sizes with ZeroDivisionError [3 pull requests]

Your current environment

OS : macOS 26.5 (arm64) Python : 3.12.11 PyTorch : 2.11.0 vLLM : 0.1.dev1+g4438b6e7d (git sha: 4438b6e7d, matches current main) Transformers : 5.9.0

Built from source via VLLM_TARGET_DEVICE=empty pip install -e . against pinned upstream commit 4438b6e7d. The bug is in pure-Python config/ KV-cache resolver code; no kernel build needed.

🐛 Describe the bug

--hash-block-size 0 is accepted by argparse, passes through CacheConfig (which uses SkipValidation[int]), and crashes engine init with ZeroDivisionError at vllm/v1/core/kv_cache_utils.py:628 (bs % hash_block_size in resolve_kv_cache_block_sizes). The adjacent Invalid hash_block_size=… ValueError two lines later is never reached. Same shape as #43496; same one-line fix shape as #43514.

Reproduction

Reachable for multi-group KV caches (hybrid Mamba+Attention models — Falcon-Mamba, RecurrentGemma, Zamba) with --enable-prefix-caching or a KV transfer connector. Single-group setups early-return at kv_cache_utils.py:577.

Minimal isolated reproducer (exercises the crash site without model loading):

from unittest.mock import MagicMock
import vllm.v1.core.kv_cache_utils as kvu

g1 = MagicMock(); g1.kv_cache_spec.block_size = 16
g2 = MagicMock(); g2.kv_cache_spec.block_size = 32
g1.kv_cache_spec.__class__ = type("Spec", (), {})
g2.kv_cache_spec.__class__ = type("Spec", (), {})

kvc = MagicMock(); kvc.kv_cache_groups = [g1, g2]
cfg = MagicMock()
cfg.cache_config.block_size = 16
cfg.cache_config.hash_block_size = 0          # bad input
cfg.cache_config.enable_prefix_caching = True
cfg.parallel_config.decode_context_parallel_size = 1
cfg.parallel_config.prefill_context_parallel_size = 1
cfg.kv_transfer_config = None

kvu.resolve_kv_cache_block_sizes(kvc, cfg)

Observed

  File "vllm/v1/core/kv_cache_utils.py", line 628, in resolve_kv_cache_block_sizes
    if any(bs % hash_block_size != 0 for bs in group_block_sizes):
       ~~~^~~~~~~~~~~~~~~~~
ZeroDivisionError: integer modulo by zero

Expected

ValueError: hash_block_size must be a positive integer, got 0. at config-construction time.

Trace (against main @ 4438b6e7d)

How this was found

Static audit of every SkipValidation[int] field in vllm/config/*.py (only two exist: block_size → #43496, and hash_block_size → this issue). Witnessed by an ESBMC (https://github.com/esbmc/esbmc) counterexample plus the sandbox reproducer above. PoC repo: lucasccordeiro/vllm.

Proposed fix

Mirrors #43514:

# extend CacheConfig._apply_block_size_default:
if self.hash_block_size is not None and self.hash_block_size <= 0:
    raise ValueError(
        f"hash_block_size must be a positive integer, got {self.hash_block_size}."
    )

The Pydantic-Field route (gt=0) is blocked by the same SkipValidation limitation that prompted #43514's approach. Happy to PR if useful.

Pre-submission checklist:

• Searched existing issues for hash_block_size and ZeroDivisionError — no prior report.
• Reproduced empirically (traceback above) and independently witnessed by an ESBMC counterexample.
• Trace verified against pinned commit 4438b6e7d.

Before submitting a new issue...

• Make sure you already searched for relevant issues, and asked the chatbot living at the bottom right corner of the documentation page, which can answer lots of frequently asked questions.