apache/beam · error · ValueError

document_field cannot be empty

Error message

document_field cannot be empty

What it means

LangChainChunker.__init__ raises this ValueError when the document_field argument is empty (None or empty string). document_field names the key in each input dict that holds the text to split, so without it the chunker cannot locate content in incoming records. Validation happens at construction time so the pipeline fails fast before submission.

Source

Thrown at sdks/python/apache_beam/ml/rag/chunking/langchain.py:87

      ```

    Args:
      text_splitter: A LangChain TextSplitter instance that defines how
        documents are split into chunks.
      metadata_fields: List of field names to copy from input documents to
        chunk metadata. These fields will be preserved in each chunk created
        from the document.
      chunk_id_fn: Optional function that take a Chunk and return str to
        generate chunk IDs. If not provided, random UUIDs will be used.
    """
    if not TextSplitter:
      raise ImportError(
          "langchain is required to use LangChainChunker"
          "Please install it with using `pip install langchain`.")
    if not isinstance(text_splitter, TextSplitter):
      raise TypeError("text_splitter must be a LangChain TextSplitter")
    if not document_field:
      raise ValueError("document_field cannot be empty")
    super().__init__(chunk_id_fn)
    self.text_splitter = text_splitter
    self.document_field = document_field
    self.metadata_fields = metadata_fields

  def get_splitter_transform(
      self
  ) -> beam.PTransform[beam.PCollection[dict[str, Any]],
                       beam.PCollection[Chunk]]:
    return "Langchain text split" >> beam.ParDo(
        _LangChainTextSplitter(
            text_splitter=self.text_splitter,
            document_field=self.document_field,
            metadata_fields=self.metadata_fields))


class _LangChainTextSplitter(beam.DoFn):
  def __init__(

View on GitHub (pinned to 12126d8942)

Solutions

1. Pass a non-empty document_field matching the key of the text content in your input dicts (commonly 'contents' for Beam RAG pipelines).
2. If loading from config, validate the field name exists before constructing the chunker.
3. Ensure your input PCollection dicts actually contain that key so a later KeyError doesn't occur.

Example fix

// before
chunker = LangChainChunker(text_splitter=splitter, document_field='')

// after
chunker = LangChainChunker(text_splitter=splitter, document_field='contents')

def validate_chunker_config(config: dict) -> str:
    field = config.get('document_field') or ''
    if not field:
        raise ValueError('document_field is required and cannot be empty')
    return field

def has_document_field(config) -> bool:
    return bool(isinstance(config, dict) and config.get('document_field'))

try:
    chunker = LangChainChunker(text_splitter=splitter, document_field=cfg['document_field'])
except ValueError as e:
    logging.error('Invalid chunker config: %s', e)
    raise

When it happens

Trigger: Calling LangChainChunker(text_splitter=..., document_field='') or omitting document_field so it defaults to None/empty; building the arg programmatically from config where the field name key is missing.

Common situations: YAML/JSON pipeline config with a missing or blank document_field entry; renaming the input record key (e.g. 'content' vs 'contents') and forgetting to update document_field; copying example code and deleting the argument.

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

• Subclasses must implement get_splitter_transform
• Expected text content in {type(item).__name__} {item.id}, go
• Expected image content in {type(item).__name__} {item.id}, g
• Expected image content in {type(item).__name__} {item.id}, g
• Item {item.id} missing embedding

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