jax-ml/jax · error · ValueError

{sliding_window=} must be positive.

Error message

{sliding_window=} must be positive.

What it means

When a sliding window is supplied to ragged_paged_attention it must be a positive integer (window size in tokens). A zero or negative window is meaningless and is rejected by static_validate_inputs before kernel launch.

Source

Thrown at jax/experimental/pallas/ops/tpu/ragged_paged_attention/kernel.py:272

  if cu_q_lens.shape != (max_num_seqs + 1,):
    raise ValueError(
        f"Expected {cu_q_lens.shape=} to be ({max_num_seqs + 1},)  where"
        " `max_num_seqs` is `page_indices.shape[0]`."
    )
  if (
      kv_lens.dtype != jnp.int32
      or page_indices.dtype != jnp.int32
      or cu_q_lens.dtype != jnp.int32
  ):
    raise ValueError(
        "The dtype of `kv_lens`, `page_indices`, and `cu_q_lens` must be"
        f" int32. Got {kv_lens.dtype=}, {page_indices.dtype=},"
        f" {cu_q_lens.dtype=}."
    )
  if num_q_heads % num_kv_heads != 0:
    raise ValueError(f"{num_q_heads=} must be divisible by {num_kv_heads=}")
  if sliding_window is not None and sliding_window <= 0:
    raise ValueError(f"{sliding_window=} must be positive.")
  if soft_cap is not None and soft_cap == 0.0:
    raise ValueError(f"{soft_cap=} must not be 0.0.")
  if (
      num_kv_pages_per_block is not None
      and not 0 < num_kv_pages_per_block <= pages_per_seq
  ):
    raise ValueError(
        f"{num_kv_pages_per_block=} must be in range (0, {pages_per_seq}]."
    )
  if num_queries_per_block is not None and num_queries_per_block <= 0:
    raise ValueError(f"{num_queries_per_block=} must be positive.")
  if vmem_limit_bytes is not None and vmem_limit_bytes <= 0:
    raise ValueError(f"{vmem_limit_bytes=} must be positive.")
  del sm_scale  # No constraints on sm_scale.
  del mask_value  # No consstraints on mask_value.


def ragged_paged_attention_kernel(

View on GitHub (pinned to 1e1c6a8fc0)

Solutions

1. Pass sliding_window=None to disable windowing instead of 0
2. Otherwise pass the actual positive window size (e.g. 4096)
3. Sanitize config values: sliding_window = cfg.window or None

Example fix

// before
attn(..., sliding_window=0)  # intended 'no window'
// after
attn(..., sliding_window=None)

sliding_window = sliding_window if (sliding_window is None or sliding_window > 0) else None

When it happens

Trigger: Passing sliding_window=0 (often intended to mean 'disabled'), a negative value, or a config default like -1 that means 'no window' elsewhere.

Common situations: Porting configs from HuggingFace / vLLM style code where sliding_window=None and sliding_window=0 both conventionally mean no window; here 0 is an error rather than a no-op.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Number of cores or threads must be at least 1, but got {self
• Vector clock size must be at least 1, but got {self.vector_c
• {soft_cap=} must not be 0.0.
• Block sizes for dq kernel are not needed with a fused kernel
• Compiler params for platform {platform} cannot be used for {

AI-assisted analysis of jax-ml/jax@1e1c6a8fc0 (2026-08-27). Data as JSON: /api/errors/98a24ea89c756190. Report an issue: GitHub.