{"record":{"id":"149344efc7b02a34","repo":"jax-ml/jax","slug":"chunk-size-must-be-positive","errorCode":null,"errorMessage":"chunk_size must be positive","messagePattern":"chunk_size must be positive","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"jax/experimental/pallas/ops/tpu/splash_attention/splash_attention_mask.py","lineNumber":111,"sourceCode":"\ndef make_chunk_attention_mask(\n    shape: tuple[int, int], chunk_size: int\n) -> np.ndarray:\n  \"\"\"Makes a chunked causal attention mask.\n\n  Args:\n    shape: The desired shape of the mask (q_seq_len, kv_seq_len).\n    chunk_size: The size of the attention chunks.\n\n  Returns:\n    A boolean mask of shape `mask_shape` where True indicates attention is\n    allowed according to chunked causal rules, and False otherwise.\n\n  Raises:\n    ValueError: If chunk_window_size is None or not positive.\n  \"\"\"\n  if chunk_size <= 0:\n    raise ValueError('chunk_size must be positive')\n\n  q_seq_len, kv_seq_len = shape\n  q_idx = np.arange(q_seq_len, dtype=np.int32)\n  kv_idx = np.arange(kv_seq_len, dtype=np.int32)\n\n  # chunk mask calculation\n  same_chunk = (q_idx[:, None] // chunk_size) == (kv_idx[None, :] // chunk_size)\n  mask = same_chunk & (q_idx[:, None] >= kv_idx[None, :])\n  return mask\n\n\ndef make_random_mask(\n    shape: tuple[int, int], sparsity: float, seed: int\n) -> np.ndarray:\n  \"\"\"Makes a random attention mask.\"\"\"\n  np.random.seed(seed)\n  return np.random.binomial(n=1, p=1.0 - sparsity, size=shape).astype(np.bool_)\n","sourceCodeStart":93,"sourceCodeEnd":129,"githubUrl":"https://github.com/jax-ml/jax/blob/1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb/jax/experimental/pallas/ops/tpu/splash_attention/splash_attention_mask.py#L93-L129","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass a positive chunk_size (typically a power of two like 128 or 1024)","Guard derived chunk sizes: chunk_size = max(1, computed) or validate config early","Fail fast on invalid config at startup instead of at mask construction"],"exampleFix":"// before\nmake_chunk_attention_mask((q, kv), chunk_size=q // num_chunks)  # 0 if num_chunks > q\n// after\nchunk_size = max(1, q // num_chunks)\nmake_chunk_attention_mask((q, kv), chunk_size=chunk_size)","handlingStrategy":"validation","validationCode":"if chunk_size <= 0:\n    raise ValueError('chunk_size must be positive')  # fail fast at config load","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate config values at startup","Use max(1, derived_chunk_size) for computed values"],"tags":["jax","splash-attention","mask","chunked-attention","argument-validation"],"backgroundTag":"invalid-argument-value","analyzedSha":"1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb","analyzedAt":"2026-08-27T09:53:25.647Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}