{"record":{"id":"2dbd8c0bbe6c39ae","repo":"apache/beam","slug":"batch-type-must-be-list-t-for-element-type-t","errorCode":null,"errorMessage":"batch type must be List[T] for element type T","messagePattern":"batch type must be List\\[T\\] for element type T","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/typehints/batch.py","lineNumber":140,"sourceCode":"  def __hash__(self) -> int:\n    return hash(self.__key())\n\n\nclass ListBatchConverter(BatchConverter):\n  SAMPLE_FRACTION = 0.2\n  MAX_SAMPLES = 100\n  SAMPLED_BATCH_SIZE = MAX_SAMPLES / SAMPLE_FRACTION\n\n  def __init__(self, batch_type, element_type):\n    super().__init__(batch_type, element_type)\n    self.element_coder = coders.registry.get_coder(element_type)\n\n  @staticmethod\n  @BatchConverter.register(name=\"list\")\n  def from_typehints(element_type, batch_type):\n    if (not isinstance(batch_type, typehints.ListConstraint) or\n        batch_type.inner_type != element_type):\n      raise TypeError(\"batch type must be List[T] for element type T\")\n\n    return ListBatchConverter(batch_type, element_type)\n\n  def produce_batch(self, elements):\n    return list(elements)\n\n  def explode_batch(self, batch):\n    return iter(batch)\n\n  def combine_batches(self, batches):\n    return sum(batches, [])\n\n  def get_length(self, batch):\n    return len(batch)\n\n  def estimate_byte_size(self, batch):\n    # randomly sample a fraction of the elements and use the element_coder to\n    # estimate the size of each","sourceCodeStart":122,"sourceCodeEnd":158,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/typehints/batch.py#L122-L158","documentation":"ListBatchConverter.from_typehints is the registered 'list' BatchConverter; it only accepts a batch_type that is a List typehint whose inner element type exactly equals the given element_type (e.g. List[float] for element_type float). Any other pairing cannot be converted to/from a Python list batch.","triggerScenarios":"from_typehints(T, SomeOtherType) hitting the 'list' registered converter with a non-list batch_type, or a List whose inner type differs from element_type (e.g. from_typehints(int, List[str])).","commonSituations":"Using beam.typehints.List with a mismatched inner type; passing Iterable[T] or Sequence[T] instead of List[T]; copy-paste errors between element and batch hints.","solutions":["Pass batch_type = List[T] with the same T as element_type","Use standard typing List[T] which beam normalizes to ListConstraint","Choose the converter matching your actual batch type (e.g. numpy for ndarray)"],"exampleFix":"// before\nBatchConverter.from_typehints(int, Iterable[int])\n// after\nBatchConverter.from_typehints(int, List[int])","handlingStrategy":"validation","validationCode":"from apache_beam.typehints import typehints\nassert isinstance(batch_type, typehints.ListConstraint) and batch_type.inner_type == element_type","typeGuard":"from apache_beam.typehints import typehints\ndef is_list_of(batch_t, elem_t):\n    return isinstance(batch_t, typehints.ListConstraint) and batch_t.inner_type == elem_t","tryCatchPattern":null,"preventionTips":["Always declare batch hints as List[T] with T equal to the element type","Use typing.List[T] which beam normalizes correctly","Avoid Iterable/Sequence hints where List is required"],"tags":["python","apache-beam","typehints"],"backgroundTag":"type-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"}