apache/beam · error · ValueError

EmbeddableItem does not contain storable string content…

Error message

EmbeddableItem does not contain storable string content (text or image URI). {self}

What it means

EmbeddableItem.content_string derives a storable string for the item: it prefers content.text and falls back to a string image URI. If neither is present (empty text and a non-string/absent image), there is nothing storable, so it raises ValueError.

Solutions

Set content.text on the item before computing content_string
If the content is an image, pass its URI as a str in Content(image='gs://...'), not bytes
Guard with hasattr/if checks or catch ValueError and skip items without storable content
Check upstream extraction for documents that produce an empty Content

Example fix

// before
Chunk(content=Content(image=image_bytes))
// after
Chunk(content=Content(image="gs://bucket/img.png"))  # or set content.text

Defensive patterns

Strategy: try-catch

Validate before calling

def has_storable_content(item) -> bool:
    return item.content.text is not None or isinstance(item.content.image, str)

Type guard

def has_content_string(item) -> bool:
    return item.content.text is not None or isinstance(item.content.image, str)

Try / catch

try:
    text = item.content_string
except ValueError:
    logging.warning("No storable content for %r; skipping", item)
    text = None

Prevention

Always populate content.text during document extraction
Pass image URIs as str, never raw bytes, when constructing Content
Skip or fix items with empty Content before content-dependent transforms

When it happens

Trigger: Accessing item.content_string on an EmbeddableItem constructed with content=Content(text=None, image=<non-str or None>) — e.g. image passed as bytes instead of a URI string, or both fields left unset.

Common situations: Loading documents that only contain binary image data without a URI; pipeline steps that clear text before content_string is computed; constructing Chunk/EmbeddableItem with an empty Content() by mistake.

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

Appendix: source

Thrown at sdks/python/apache_beam/ml/rag/types.py:163

  def dense_embedding(self) -> Optional[list[float]]:
    return self.embedding.dense_embedding if self.embedding else None

  @property
  def sparse_embedding(self) -> Optional[tuple[list[int], list[float]]]:
    return self.embedding.sparse_embedding if self.embedding else None

  @property
  def content_string(self) -> str:
    """Returns storable string content for ingestion.

    Falls back through content fields in priority order:
    text > image URI.
    """
    if self.content.text is not None:
      return self.content.text
    if isinstance(self.content.image, str):
      return self.content.image
    raise ValueError(
        f'EmbeddableItem does not contain storable string content'
        f' (text or image URI). {self}')


# Backward compatibility alias. Existing code using Chunk continues to work
# unchanged since Chunk IS EmbeddableItem.
Chunk = EmbeddableItem

View on GitHub (pinned to 12126d8942)