apache/beam · error · ValueError

Expected image content in {type(item).name} {item.id}, g

Error message

Expected image content in {type(item).__name__} {item.id}, got None

What it means

VertexAIImageEmbeddings processes items that must carry image data in item.content.image. _extract_images iterates over a batch of EmbeddableItem objects and raises ValueError when any item's content.image is None, because a vertexai Image object cannot be constructed from missing data. This is a fail-fast check so a bad item does not silently produce an empty embedding.

Source

Thrown at sdks/python/apache_beam/ml/rag/embeddings/vertex_ai.py:112

        credentials=self.credentials,
    )

  def get_ptransform_for_processing(
      self, **kwargs
  ) -> beam.PTransform[beam.PCollection[EmbeddableItem],
                       beam.PCollection[EmbeddableItem]]:
    """Returns PTransform that uses the RAG adapter."""
    return RunInference(
        model_handler=_TextEmbeddingHandler(self),
        inference_args=self.inference_args).with_output_types(EmbeddableItem)


def _extract_images(items: Sequence[EmbeddableItem]) -> list:
  """Extract images from items and convert to vertexai Image objects."""
  images = []
  for item in items:
    if not item.content.image:
      raise ValueError(
          "Expected image content in "
          f"{type(item).__name__} {item.id}, "
          "got None")
    img_data = item.content.image
    if isinstance(img_data, bytes):
      images.append(Image(image_bytes=img_data))
    else:
      images.append(Image.load_from_file(img_data))
  return images


def _create_image_adapter(
) -> EmbeddingTypeAdapter[EmbeddableItem, EmbeddableItem]:
  """Creates adapter for Vertex AI image embedding.

  Extracts content.image from EmbeddableItems and converts
  to vertexai.vision_models.Image objects. Supports both
  raw bytes and file paths/URIs.

View on GitHub (pinned to 12126d8942)

Solutions

Populate item.content.image with valid image bytes before the embedding step.
Filter or partition the PCollection so only items with non-None content.image reach VertexAIImageEmbeddings.
Use VertexAITextEmbeddings for text-only items.
Wrap extraction with a pre-check that drops/logs items missing image content instead of failing the whole batch.

Example fix

// before
items = [EmbeddableItem(id='a', content=Content(image=None))]
embeddings = VertexAIImageEmbeddings(...)
// after
items = [EmbeddableItem(id='a', content=Content(image=img_bytes))]
# or filter:
items = [it for it in items if it.content.image is not None]
embeddings = VertexAIImageEmbeddings(...)

Defensive patterns

Strategy: validation

Validate before calling

def has_image(item):
    return item.content is not None and item.content.image is not None
valid_items = [it for it in items if has_image(it)]

Type guard

def is_embeddable_image(item) -> bool:
    try:
        return isinstance(item.content.image, (bytes, bytearray))
    except AttributeError:
        return False

Try / catch

try:
    results = embedder.expand(pcoll)
except ValueError as e:
    if 'Expected image content' in str(e):
        logging.error('Non-image item in image embedding batch: %s', e)
        raise

Prevention

Filter text items away from image embedders with a separate branch in the pipeline.
Assert image bytes are populated right after the ingestion transform.
Use VertexAITextEmbeddings for text content.

When it happens

Trigger: Calling VertexAIImageEmbeddings via RunInference/EmbeddingsManager over a PCollection of EmbeddableItem where at least one item has content set to text-only or content.image is None (e.g. items built from text chunks, or image bytes never populated in the pipeline).

Common situations: Mixed-text/image datasets where text items flow into an image embedder; a parse/ingestion step that fails to set image bytes; using the wrong embedder class (VertexAITextEmbeddings vs VertexAIImageEmbeddings) for the data.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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