What causes "batch type must be List[T] for element type T" in apache/beam?

Pass batch_type = List[T] with the same T as element_type

apache/beam · error · TypeError

batch type must be List[T] for element type T

Error message

batch type must be List[T] for element type T

What it means

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.

Source

Thrown at sdks/python/apache_beam/typehints/batch.py:140

  def __hash__(self) -> int:
    return hash(self.__key())


class ListBatchConverter(BatchConverter):
  SAMPLE_FRACTION = 0.2
  MAX_SAMPLES = 100
  SAMPLED_BATCH_SIZE = MAX_SAMPLES / SAMPLE_FRACTION

  def __init__(self, batch_type, element_type):
    super().__init__(batch_type, element_type)
    self.element_coder = coders.registry.get_coder(element_type)

  @staticmethod
  @BatchConverter.register(name="list")
  def from_typehints(element_type, batch_type):
    if (not isinstance(batch_type, typehints.ListConstraint) or
        batch_type.inner_type != element_type):
      raise TypeError("batch type must be List[T] for element type T")

    return ListBatchConverter(batch_type, element_type)

  def produce_batch(self, elements):
    return list(elements)

  def explode_batch(self, batch):
    return iter(batch)

  def combine_batches(self, batches):
    return sum(batches, [])

  def get_length(self, batch):
    return len(batch)

  def estimate_byte_size(self, batch):
    # randomly sample a fraction of the elements and use the element_coder to
    # estimate the size of each

View on GitHub (pinned to 12126d8942)

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)

Example fix

// before
BatchConverter.from_typehints(int, Iterable[int])
// after
BatchConverter.from_typehints(int, List[int])

Defensive patterns

Strategy: validation

Validate before calling

from apache_beam.typehints import typehints
assert isinstance(batch_type, typehints.ListConstraint) and batch_type.inner_type == element_type

Type guard

from apache_beam.typehints import typehints
def is_list_of(batch_t, elem_t):
    return isinstance(batch_t, typehints.ListConstraint) and batch_t.inner_type == elem_t

Prevention

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

When it happens

Trigger: 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])).

Common situations: 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.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/2dbd8c0bbe6c39ae. Report an issue: GitHub.