sgl-project/sglang · error · ValueError

realtime_causal_kv_cache_num_frames must be positive

Error message

realtime_causal_kv_cache_num_frames must be positive

What it means

The realtime_causal_kv_cache_num_frames override (from request or pipeline_config) must be > 0 because it defines the sliding-window frame count for the causal KV cache.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/causal_denoising.py:417

        if sink_size is not None:
            if sink_size < 0:
                raise ValueError("realtime_causal_sink_size must be non-negative")
            self.sink_size = int(sink_size)

        kv_cache_num_frames = getattr(
            batch,
            "realtime_causal_kv_cache_num_frames",
            None,
        )
        if kv_cache_num_frames is None:
            kv_cache_num_frames = getattr(
                pipeline_config,
                "realtime_causal_kv_cache_num_frames",
                None,
            )
        if kv_cache_num_frames is not None:
            if kv_cache_num_frames <= 0:
                raise ValueError("realtime_causal_kv_cache_num_frames must be positive")
            self.sliding_window_num_frames = int(kv_cache_num_frames)

        if (
            server_args.kv_cache_quant_config.enabled
            and not self._supports_qvg_kv_cache_quantization()
        ):
            raise ValueError(
                f"{type(self).__name__} does not support QVG KV-cache quantization"
            )

    def _supports_qvg_kv_cache_quantization(self) -> bool:
        return False

    def _causal_sequence_shard_enabled(self, batch: Req) -> bool:
        return False

    def _num_causal_cache_attention_heads(
        self,

View on GitHub (pinned to 0132848349)

Solutions

1. Set a positive frame count, e.g. realtime_causal_kv_cache_num_frames=64
2. Remove/None the field to keep the stage default window

Example fix

# before
pipeline_config.realtime_causal_kv_cache_num_frames = 0
# after
pipeline_config.realtime_causal_kv_cache_num_frames = 64

n = cfg.get('realtime_causal_kv_cache_num_frames')
assert n is None or n > 0

def valid_window(v) -> bool: return v is None or (isinstance(v,int) and v > 0)

When it happens

Trigger: Setting realtime_causal_kv_cache_num_frames=0 or negative in config/request; _build_realtime_causal_cache_policy then applies overrides at stage init.

Common situations: Disabling the sliding window by setting 0 instead of removing the field; unit-of-confusion (frames vs tokens) leading to 0 after integer division; config defaults drift.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• realtime_causal_sink_size must be non-negative
• kv-canary: RealKvSource.page_size must be >= 1, got {self.pa
• BatchedDecodeContext requires full_kv_pool_index_by_layer wh
• Unknown KV cache quantization method: '{name}'. Available: {
• v_cache must be provided

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