{"record":{"id":"ab3424ca31ac455a","repo":"jax-ml/jax","slug":"expected-a-single-dimension-when-passing-a-single","errorCode":null,"errorMessage":"Expected a single dimension when passing a single index","messagePattern":"Expected a single dimension when passing a single index","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"jax/experimental/mosaic/gpu/utils.py","lineNumber":2362,"sourceCode":"\ndef cluster_idx(\n    dim: gpu.Dimension | Sequence[gpu.Dimension] | None = None,\n    dim_idx: ir.Value | Sequence[ir.Value] | None = None,\n) -> ir.Value:\n  \"\"\"Returns the linear index of a block within a subset of the cluster spanned by the given dimensions.\n\n  dim_idx can be used to specify the index of another block along the selected\n  dimensions. If not provided, the current block's index is used.\n  \"\"\"\n  if dim is None:\n    dim = tuple(gpu.Dimension)\n  elif isinstance(dim, gpu.Dimension):\n    dim = (dim,)\n  if dim_idx is None:\n    dim_idx = [gpu.cluster_block_id(d) for d in dim]\n  elif isinstance(dim_idx, ir.Value):\n    if len(dim) != 1:\n      raise ValueError(\n          \"Expected a single dimension when passing a single index\"\n      )\n    dim_idx = [dim_idx]\n  index = ir.IndexType.get()\n  stride = c(1, index)\n  lin_idx = c(0, index)\n  for d, idx in sorted(zip(dim, dim_idx, strict=True), key=lambda x: x[0]):\n    lin_idx = arith.addi(lin_idx, arith.muli(idx, stride))\n    stride = arith.muli(stride, gpu.cluster_dim_blocks(d))\n  return lin_idx\n\n\ndef get_cluster_ptr(\n    ptr: ir.Value, cluster_block: ir.Value, generic: bool = True\n):\n  i32 = ir.IntegerType.get_signless(32)\n  assert cluster_block.type == i32, cluster_block.type\n  assert ptr.type == llvm.PointerType.get(3), ptr.type","sourceCodeStart":2344,"sourceCodeEnd":2380,"githubUrl":"https://github.com/jax-ml/jax/blob/1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb/jax/experimental/mosaic/gpu/utils.py#L2344-L2380","documentation":"Raised in cluster_idx (utils.py:2362) when the caller passes a single scalar dim_idx (an ir.Value) while specifying multiple dims. A scalar index can only broadcast against one dimension, so the combination is ambiguous.","triggerScenarios":"Calling utils.cluster_idx(dim=(gpu.Dimension.x, gpu.Dimension.y), dim_idx=some_value) — more than one dim but dim_idx is a single ir.Value rather than a sequence.","commonSituations":"Refactoring code that indexed one dimension and adding another dim without turning dim_idx into a list; copy-pasting multi-dim calls from single-dim examples.","solutions":["Pass dim_idx as a sequence matching len(dim), e.g. [idx_x, idx_y]","Or pass dim as a single gpu.Dimension if only one index is available"],"exampleFix":"# before\ncluster_idx(dim=(gpu.Dimension.x, gpu.Dimension.y), dim_idx=idx)\n# after\ncluster_idx(dim=(gpu.Dimension.x, gpu.Dimension.y), dim_idx=[idx_x, idx_y])","handlingStrategy":"validation","validationCode":"idx = dim_idx if isinstance(dim_idx, (list, tuple)) else ([dim_idx] if dim_idx is not None else None)\nassert idx is None or len(idx) == len(dim)","typeGuard":null,"tryCatchPattern":"try:\n    cluster_idx(dim=dim, dim_idx=dim_idx)\nexcept ValueError as e:\n    if 'single dimension' in str(e):\n        dim_idx = [dim_idx] * len(dim)\n    else:\n        raise","preventionTips":["Always pass dim_idx as a sequence","Keep dim and dim_idx lengths in sync in kernel configs"],"tags":["jax","mosaic-gpu","cluster","api-misuse"],"backgroundTag":"argument-shape-mismatch","analyzedSha":"1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb","analyzedAt":"2026-08-27T09:53:25.647Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}