{"record":{"id":"36e4535b39695d81","repo":"apache/beam","slug":"failed-to-align-batch-type-s-batch-dimension-with-element","errorCode":null,"errorMessage":"Failed to align batch type's batch dimension with element type. (batch type dimensions: {batch_type.shape}, element type dimenstions: {element_type.shape}","messagePattern":"Failed to align batch type's batch dimension with element type\\. \\(batch type dimensions: (.+?), element type dimenstions: (.+?)","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/typehints/batch.py","lineNumber":210,"sourceCode":"        raise TypeError(\"Element type is not a dtype\") from e\n\n    if not isinstance(batch_type, NumpyTypeHint.NumpyTypeConstraint):\n      if not batch_type == np.ndarray:\n        raise TypeError(\n            \"batch type must be np.ndarray or \"\n            \"beam.typehints.batch.NumpyArray[..]\")\n      batch_type = NumpyArray[element_type.dtype, (N, )]\n\n    if not batch_type.dtype == element_type.dtype:\n      raise TypeError(\n          \"batch type and element type must have equivalent dtypes \"\n          f\"(batch={batch_type.dtype}, element={element_type.dtype})\")\n\n    computed_element_shape = list(batch_type.shape)\n    partition_dimension = computed_element_shape.index(N)\n    computed_element_shape.pop(partition_dimension)\n    if not tuple(computed_element_shape) == element_type.shape:\n      raise TypeError(\n          \"Failed to align batch type's batch dimension with element type. \"\n          f\"(batch type dimensions: {batch_type.shape}, element type \"\n          f\"dimenstions: {element_type.shape}\")\n\n    return NumpyBatchConverter(\n        batch_type,\n        element_type,\n        batch_type.dtype,\n        element_type.shape,\n        partition_dimension)\n\n  def produce_batch(self, elements):\n    return np.stack(elements, axis=self.partition_dimension)\n\n  def explode_batch(self, batch):\n    \"\"\"Convert an instance of B to Generator[E].\"\"\"\n    yield from batch.swapaxes(self.partition_dimension, 0)\n","sourceCodeStart":192,"sourceCodeEnd":228,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/typehints/batch.py#L192-L228","documentation":"The batch type's shape must contain exactly one N (the batch/partition dimension) and removing it must yield the element type's shape. If the remaining dimensions don't equal element_type.shape, shapes cannot be aligned.","triggerScenarios":"from_typehints(NumpyArray[np.float64, (3,)], NumpyArray[np.float64, (N,)]) — batch is 1-D but element is 1-D with size 3, removing N gives () which != (3,); or batch hint shape with wrong ordering of dims around N.","commonSituations":"Declaring scalar elements but batching into 2-D arrays or vice versa; hand-writing NumpyArray shapes where the N placement doesn't match the element shape.","solutions":["Ensure batch shape is element shape with a single N inserted at the batching axis, e.g. element (3,) -> batch (N, 3)","Check the shape you pass to NumpyArray[dtype, shape] counts all element dims","Use () element shape for 1-D batches of scalars"],"exampleFix":"// before\nBatchConverter.from_typehints(NumpyArray[np.float64, (3,)], NumpyArray[np.float64, (N,)])\n// after\nBatchConverter.from_typehints(NumpyArray[np.float64, (3,)], NumpyArray[np.float64, (N, 3)])","handlingStrategy":"validation","validationCode":"# element shape (3,) -> batch shape (N, 3)\nassert batch_shape.count(N) == 1\ncomputed = tuple(d for d in batch_shape if d != N)\nassert computed == element_shape","typeGuard":"def shapes_align(batch_shape, elem_shape, N):\n    if batch_shape.count(N) != 1: return False\n    dims = list(batch_shape); dims.remove(N)\n    return tuple(dims) == tuple(elem_shape)","tryCatchPattern":null,"preventionTips":["Insert exactly one N into the element shape at the batching axis","Keep element and batch shape declarations in sync","For scalar elements use element shape () and batch shape (N,)"],"tags":["python","apache-beam","numpy","shape"],"backgroundTag":"tensor-shape-mismatch","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T21:17:11.552Z"}