{"record":{"id":"1c3c805e75ea7244","repo":"apache/beam","slug":"batch-type-must-be-np-ndarray-or-beam-typehints-batch","errorCode":null,"errorMessage":"batch type must be np.ndarray or beam.typehints.batch.NumpyArray[..]","messagePattern":"batch type must be np\\.ndarray or beam\\.typehints\\.batch\\.NumpyArray\\[\\.\\.\\]","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/typehints/batch.py","lineNumber":196,"sourceCode":"      partition_dimension=0):\n    super().__init__(batch_type, element_type)\n    self.dtype = np.dtype(dtype)\n    self.element_shape = element_shape\n    self.partition_dimension = partition_dimension\n\n  @staticmethod\n  @BatchConverter.register(name=\"numpy\")\n  def from_typehints(element_type,\n                     batch_type) -> Optional['NumpyBatchConverter']:\n    if not isinstance(element_type, NumpyTypeHint.NumpyTypeConstraint):\n      try:\n        element_type = NumpyArray[element_type, ()]\n      except TypeError as e:\n        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","sourceCodeStart":178,"sourceCodeEnd":214,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/typehints/batch.py#L178-L214","documentation":"NumpyBatchConverter.from_typehints requires the batch type to be np.ndarray or a NumpyArray[...] typehint (optionally with a shape/partition dimension); the supplied batch_type is neither, so no numpy-based batching applies. This converter returning None/raising lets BatchConverter pick the right implementation.","triggerScenarios":"from_typehints(np.int64, List[int]) or from_typehints(np.int64, np.matrix) — batch type is neither a NumpyArray[..] hint nor np.ndarray.","commonSituations":"Mixing list and numpy batching hints; passing array subclasses instead of np.ndarray.","solutions":["Pass batch_type = np.ndarray or NumpyArray[dtype, shape]","Wrap the batch type as beam.typehints.batch.NumpyArray[dtype, (N,)]","Use the list converter if batches are Python lists"],"exampleFix":"// before\nBatchConverter.from_typehints(np.int64, List[int])\n// after\nBatchConverter.from_typehints(np.int64, np.ndarray)","handlingStrategy":"validation","validationCode":"import numpy as np\nfrom apache_beam.typehints.batch import NumpyArray, NumpyTypeHint\nassert isinstance(batch_type, NumpyTypeHint.NumpyTypeConstraint) or batch_type == np.ndarray","typeGuard":"import numpy as np\ndef is_numpy_batch_type(bt):\n    return bt == np.ndarray or isinstance(getattr(bt, 'dtype', None), np.dtype)","tryCatchPattern":null,"preventionTips":["Use exactly np.ndarray or NumpyArray[dtype, shape] as the numpy batch hint","Don't mix list batch hints with the numpy converter","Normalize array subclasses to np.ndarray"],"tags":["python","apache-beam","numpy","typehints"],"backgroundTag":"incompatible-source-type","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"}