{"record":{"id":"700a6176f1681659","repo":"jax-ml/jax","slug":"cluster-must-be-at-most-3d-got-self","errorCode":null,"errorMessage":"cluster= must be at most 3D, got {self}.","messagePattern":"cluster= must be at most 3D, got (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"jax/_src/pallas/mosaic_gpu/core.py","lineNumber":1640,"sourceCode":"    )\n\n\n_WARPGROUP_AXIS_NAME = object()\n\n@dataclasses.dataclass(frozen=True, kw_only=True)\nclass Mesh(pallas_core.Mesh):\n  grid: Sequence[int] = ()\n  grid_names: Sequence[str] = ()\n  cluster: Sequence[int] = ()\n  cluster_names: Sequence[str] = ()\n  # Those are NOT CUDA threads. On Hopper they correspond to warpgroups.\n  num_threads: int | None = None\n  thread_name: str | None = None\n  kernel_name: str | None = None\n\n  def __post_init__(self):\n    if len(self.cluster) > 3:\n      raise ValueError(f\"cluster= must be at most 3D, got {self}.\")\n    if len(self.grid_names) != len(self.grid):\n      raise ValueError(\n          f\"grid_names must have the same length as grid, got {self}.\"\n      )\n    if len(self.cluster_names) != len(self.cluster):\n      raise ValueError(\n          f\"cluster_names must have the same length as cluster, got {self}.\"\n      )\n    if (self.thread_name is None) != (self.num_threads is None):\n      raise ValueError(\n          \"num_threads and thread_name must be either both set or both None,\"\n          f\" got {self}\"\n      )\n    max_mosaic_threads = 2048 // 128\n    if self.num_threads is not None and self.num_threads > max_mosaic_threads:\n      raise ValueError(\n          \"Requested too many CUDA threads per block. Each Mosaic thread\"\n          f\" corresponds to 128 CUDA threads. At most {max_mosaic_threads}\"","sourceCodeStart":1622,"sourceCodeEnd":1658,"githubUrl":"https://github.com/jax-ml/jax/blob/1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb/jax/_src/pallas/mosaic_gpu/core.py#L1622-L1658","documentation":"Raised by WarpSpecialized or launch-config dataclass __post_init__ validation: the `cluster` tuple describing the thread-block cluster shape has more than 3 dimensions. CUDA clusters are limited to at most 3D (x, y, z), so Mosaic rejects longer tuples at config construction time.","triggerScenarios":"Creating a GPU kernel launch/config object (e.g. a WarpSpecialized descriptor or launch metadata) with `cluster=(2,2,2,2)` or any tuple of length > 3.","commonSituations":"Copying a multi-dimensional `grid` (which may be longer) into `cluster=`; refactoring code where grid and cluster were previously the same tuple; upgrading JAX versions where cluster support tightened validation.","solutions":["Reduce cluster= to at most 3 dimensions, e.g. `cluster=(2, 2, 2)`","Fold extra parallelism into grid= instead of cluster="],"exampleFix":"// before\ncluster=(2, 2, 2, 2)\n\n// after\ncluster=(2, 2, 2)  # move the 4th factor into grid","handlingStrategy":"validation","validationCode":"assert len(cluster) <= 3, f'cluster must be <= 3D, got {len(cluster)}'","typeGuard":"def is_valid_cluster(cluster: tuple) -> bool:\n    return 1 <= len(cluster) <= 3","tryCatchPattern":"try:\n    cfg = MyConfig(cluster=cluster)\nexcept ValueError as e:\n    cluster = cluster[:3]  # or rebalance into grid\n    cfg = MyConfig(cluster=cluster)","preventionTips":["Keep cluster tuples 1-3D by construction","Push extra parallelism into grid, not cluster","Centralize launch-config creation in one validated factory"],"tags":["jax","pallas","mosaic-gpu","cluster","launch-config","validation"],"backgroundTag":"invalid-launch-configuration","analyzedSha":"1e1c6a8fc06dfcd1247076ec5cae4640cea5d7bb","analyzedAt":"2026-08-27T09:53:25.647Z","schemaVersion":2},"datasetVersion":"2026-08-27T13:17:12.746Z"}