{"record":{"id":"d12e045497b30408","repo":"jax-ml/jax","slug":"bkv-compute-must-be-a-multiple-of-num-lanes","errorCode":null,"errorMessage":"{bkv_compute=} must be a multiple of {NUM_LANES}.","messagePattern":"(.+?) must be a multiple of (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"jax/experimental/pallas/ops/tpu/splash_attention/splash_attention_kernel.py","lineNumber":971,"sourceCode":"    )\n\n  if not is_mqa and num_q_heads % num_kv_heads != 0:\n    raise ValueError(\n        f\"In MHA, expected number of 'key' heads ({num_kv_heads}) to be a\"\n        f\" multiple of the number of 'query' heads ({num_q_heads})\"\n    )\n\n  if k.shape[:-1] != v.shape[:-1]:\n    raise ValueError(\n        f\"Expected 'key' {k.shape} and 'value' {v.shape} to have the same \"\n        \"leading dimensions.\"\n    )\n\n  assert bkv_compute is not None\n  if bkv % bkv_compute:\n    raise ValueError(f\"{bkv=} must be a multiple of {bkv_compute=}.\")\n  if bkv_compute % NUM_LANES:\n    raise ValueError(f\"{bkv_compute=} must be a multiple of {NUM_LANES}.\")\n\n  kv_seq_len = k.shape[kv_seq_len_dimension]\n\n  q_heads_per_kv_head = num_q_heads // num_kv_heads\n\n  if segment_ids is not None:\n    if segment_ids.q.shape != (q_seq_len,):\n      raise ValueError(\n          \"Invalid shape for q segment_ids: \"\n          f\"{segment_ids.q.shape}. Expected: {(q_seq_len,)}\"\n      )\n    if segment_ids.kv.shape != (kv_seq_len,):\n      raise ValueError(\n          \"Invalid shape for kv segment_ids: \"\n          f\"{segment_ids.kv.shape}. Expected: {(kv_seq_len,)}\"\n      )\n\n  q_layout = block_sizes.q_layout","sourceCodeStart":953,"sourceCodeEnd":989,"githubUrl":"https://github.com/jax-ml/jax/blob/1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb/jax/experimental/pallas/ops/tpu/splash_attention/splash_attention_kernel.py#L953-L989","documentation":"block_kv_compute must itself be divisible by NUM_LANES=8 so the in-kernel softmax running-max tiling works. Even if block_kv is lane-aligned, an unaligned compute block is rejected.","triggerScenarios":"block_sizes=BlockSizes(block_kv=128, block_kv_compute=100) — 128 % 8 == 0 but 100 % 8 != 0.","commonSituations":"Fine-tuning compute tiling for TPU v5e/v6e where smaller compute blocks improve pipelining; using legacy block sizes from before this constraint existed.","solutions":["Set block_kv_compute to a multiple of 8 (64, 128, 256...)","Use the library's default block size selection (block_sizes=None)","Pin JAX to a version whose recommended block sizes you copied, or regenerate them with the current version's helper"],"exampleFix":"// before\nBlockSizes(block_kv=256, block_kv_compute=100)\n// after\nBlockSizes(block_kv=256, block_kv_compute=128)","handlingStrategy":"validation","validationCode":"assert (block_sizes.block_kv_compute or 0) % 8 == 0","typeGuard":"def lane_aligned(x) -> bool: return x is None or x % 8 == 0","tryCatchPattern":null,"preventionTips":["Keep every block size a multiple of 8","Prefer library defaults (block_sizes=None)"],"tags":["jax","pallas","tpu","splash-attention","block-size"],"backgroundTag":"block-size-constraint-violation","analyzedSha":"1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb","analyzedAt":"2026-08-27T09:53:25.647Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}