jax-ml/jax · error · ValueError

chunk_size must be positive

Error message

chunk_size must be positive

What it means

make_chunk_attention_mask requires a positive chunk_size (the per-chunk window for chunked causal attention). Zero or negative chunk sizes cannot define a chunk grid and raise ValueError immediately.

Source

Thrown at jax/experimental/pallas/ops/tpu/splash_attention/splash_attention_mask.py:111

def make_chunk_attention_mask(
    shape: tuple[int, int], chunk_size: int
) -> np.ndarray:
  """Makes a chunked causal attention mask.

  Args:
    shape: The desired shape of the mask (q_seq_len, kv_seq_len).
    chunk_size: The size of the attention chunks.

  Returns:
    A boolean mask of shape `mask_shape` where True indicates attention is
    allowed according to chunked causal rules, and False otherwise.

  Raises:
    ValueError: If chunk_window_size is None or not positive.
  """
  if chunk_size <= 0:
    raise ValueError('chunk_size must be positive')

  q_seq_len, kv_seq_len = shape
  q_idx = np.arange(q_seq_len, dtype=np.int32)
  kv_idx = np.arange(kv_seq_len, dtype=np.int32)

  # chunk mask calculation
  same_chunk = (q_idx[:, None] // chunk_size) == (kv_idx[None, :] // chunk_size)
  mask = same_chunk & (q_idx[:, None] >= kv_idx[None, :])
  return mask


def make_random_mask(
    shape: tuple[int, int], sparsity: float, seed: int
) -> np.ndarray:
  """Makes a random attention mask."""
  np.random.seed(seed)
  return np.random.binomial(n=1, p=1.0 - sparsity, size=shape).astype(np.bool_)

View on GitHub (pinned to 1e1c6a8fc0)

Solutions

1. Pass a positive chunk_size (typically a power of two like 128 or 1024)
2. Guard derived chunk sizes: chunk_size = max(1, computed) or validate config early
3. Fail fast on invalid config at startup instead of at mask construction

Example fix

// before
make_chunk_attention_mask((q, kv), chunk_size=q // num_chunks)  # 0 if num_chunks > q
// after
chunk_size = max(1, q // num_chunks)
make_chunk_attention_mask((q, kv), chunk_size=chunk_size)

if chunk_size <= 0:
    raise ValueError('chunk_size must be positive')  # fail fast at config load

When it happens

Trigger: Calling make_chunk_attention_mask(shape, chunk_size=0) or with a negative chunk_size, e.g. when a config field is read before being set or a division produces 0.

Common situations: chunk_size derived from config with a None/0 default; computing chunk_size = seq_len // n where n > seq_len yields 0; typos in hyperparameter files.

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

• Mask function must return a boolean-valued array, but got: {
• partial_mask_blocks must be of type np.bool_ but got {partia
• Unexpected mask shape: {mask.shape}
• Invalid shape for other: {other.shape}, expected: {self.shap
• Masks must have the same shape

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