apache/beam · error · TypeError

Embeddings can only be generated on dict[str, Image].Got…

Error message

Embeddings can only be generated on dict[str, Image].Got dict[str, {type(batch[0])}] instead.

What it means

The image-embedding EmbeddingsManager expects dict[str, Image]-style columns where values are framework image objects (e.g. PIL Images). To avoid framework-specific imports it rejects primitive Python values (int, str, float, bool), raising TypeError, since those can never be valid image inputs.

Solutions

Load images into the framework-specific image type (e.g. PIL.Image.open(path)) before the embedding transform.
Use the text embeddings manager (dict[str, str]) if your columns are strings.
Verify the correct column names are configured; you may be embedding a metadata column by mistake.

Example fix

// before
rows | beam.Map(lambda d: {'img': d['path']}) | image_embedding_transform
// after
rows | beam.Map(lambda d: {'img': PIL.Image.open(d['path'])}) | image_embedding_transform

Defensive patterns

Strategy: validation

Validate before calling

def validate_image_batch(batch):
    assert not isinstance(batch[0], (int, str, float, bool)), f'Not an image object: {type(batch[0])}'

Type guard

def is_image_column(values) -> bool:
    return not any(isinstance(v, (int, str, float, bool)) for v in values)

Try / catch

try:
    data | image_embedding
except TypeError as e:
    if 'dict[str, Image]' in str(e):
        data = data | beam.Map(load_images)
    else:
        raise

Prevention

Load images with PIL/framework loaders before embedding; never pass paths as str.
Match the embeddings manager to the modality (text vs image vs dataclass).
Inspect sample elements of the PCollection before the transform.
Keep metadata (paths, labels) in separate columns.

When it happens

Trigger: Applying an image embedding transform to a column containing strings/numbers (e.g. file paths as str, labels, or raw pixel ints) instead of actual image objects.

Common situations: Passing image file paths (strings) instead of loaded image objects; using the image embeddings manager where the text one was intended; a preprocessing step upstream emitted raw values.

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/5242c6fcfbe2d06e. Report an issue: GitHub.

Appendix: source

Thrown at sdks/python/apache_beam/ml/transforms/base.py:803

  _ImageEmbeddingHandler will accept an EmbeddingsManager instance, which
  contains the details of the model to be loaded and the inference_fn to be
  used. The purpose of _ImageEmbeddingHandler is to generate embeddings for
  image inputs using the EmbeddingsManager instance.

  If the input is not an Image representation column, a RuntimeError will be
  raised.

  This is an internal class and offers no backwards compatibility guarantees.

  Args:
    embeddings_manager: An EmbeddingsManager instance.
  """
  def _validate_column_data(self, batch):
    # Don't want to require framework-specific imports
    # here, so just catch columns of primatives for now.
    if isinstance(batch[0], (int, str, float, bool)):
      raise TypeError(
          'Embeddings can only be generated on dict[str, Image].'
          f'Got dict[str, {type(batch[0])}] instead.')

  def get_metrics_namespace(self) -> str:
    return (
        self._underlying.get_metrics_namespace() or
        'BeamML_ImageEmbeddingHandler')


class _MultiModalEmbeddingHandler(_EmbeddingHandler):
  """
  A ModelHandler intended to be work on
  list[dict[str, TypedDict(Image, Video, str)]] inputs.

  The inputs to the model handler are expected to be a list of dicts.

  For example, if the original mode is used with RunInference to take a
  PCollection[E] to a PCollection[P], this ModelHandler would take a

View on GitHub (pinned to 12126d8942)