apache/beam · error · TypeError

Unable to find BatchConverter for element_type={element_type

Error message

Unable to find BatchConverter for element_type={element_type!r} and batch_type={batch_type!r}. Error summaries:

{error_summaries}

What it means

BatchConverter.from_typehints tries every registered BatchConverter constructor for the given element_type/batch_type pair; if all raise TypeError, it aggregates their messages and raises this TypeError. It means no registered converter can convert between the two type hints.

Source

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

      BATCH_CONVERTER_REGISTRY[name] = batch_converter_constructor
      return batch_converter_constructor

    return do_registration

  @staticmethod
  def from_typehints(*, element_type, batch_type) -> 'BatchConverter':
    element_type = typehints.normalize(element_type)
    batch_type = typehints.normalize(batch_type)
    errors = {}
    for name, constructor in BATCH_CONVERTER_REGISTRY.items():
      try:
        return constructor(element_type, batch_type)
      except TypeError as e:
        errors[name] = e.args[0]

    error_summaries = '\n\n'.join(
        f"{name}:\n\t{msg}" for name, msg in errors.items())
    raise TypeError(
        f"Unable to find BatchConverter for element_type={element_type!r} and "
        f"batch_type={batch_type!r}. Error summaries:\n\n{error_summaries}")

  @property
  def batch_type(self):
    return self._batch_type

  @property
  def element_type(self):
    return self._element_type

  def __key(self):
    return (self._element_type, self._batch_type)

  def __eq__(self, other: 'BatchConverter') -> bool:
    if isinstance(other, BatchConverter):
      return self.__key() == other.__key()

View on GitHub (pinned to 12126d8942)

Solutions

1. Check registered converters and pass a matching pair, e.g. from_typehints(int, List[int]) for the list converter
2. Verify the batch_type parameterization matches element_type exactly (List[T] with same T)
3. Import the module that registers the converter you need (e.g. pandas/arrow converters) before calling
4. Register a custom BatchConverter for your element/batch type pair

Example fix

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

from apache_beam.typehints import batch, typehints
if not isinstance(batch_type, typehints.ListConstraint):
    raise ValueError('use List[T] as batch type')

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

try:
    conv = BatchConverter.from_typehints(elem_t, batch_t)
except TypeError as e:
    print(e)  # includes per-converter error summaries; pick a supported pair

When it happens

Trigger: Calling BatchConverter.from_typehints(element_type, batch_type) where no registered converter (list, numpy, pandas, arrow, etc.) accepts the pair, e.g. from_typehints(int, Dict[str, int]) or an unregistered custom class as batch type.

Common situations: Typo'd or mismatched type hints in BatchElements/CollapseBatches pipelines; using a batch type no converter is registered for; forgetting to import apache_beam.dataframe or pandas convertors so no constructor matches.

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

• Only dataframes with single rows are supported.
• min_batch_size must be >= 1, got {min_batch_size}
• max_batch_size ({max_batch_size}) must be >= min_batch_size
• max_batch_weight must be >= 1, got {max_batch_weight}
• element_size_fn must be callable

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