apache/beam · error · TypeError

text_splitter must be a LangChain TextSplitter

Error message

text_splitter must be a LangChain TextSplitter

What it means

LangChainChunker.__init__ raises this TypeError when the text_splitter argument is not an instance of langchain's TextSplitter class. The constructor validates the type up front so misconfiguration surfaces at pipeline construction time instead of failing inside workers mid-run. Only LangChain TextSplitter subclasses (e.g. RecursiveCharacterTextSplitter, CharacterTextSplitter) are accepted.

Source

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

            | beam.Create([{'text': 'long document...', 'source': 'doc.txt'}])
            | MLTransform(...).with_transform(chunker))
      ```

    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))

View on GitHub (pinned to 12126d8942)

Solutions

1. Pass a genuine LangChain TextSplitter instance, e.g. RecursiveCharacterTextSplitter(chunk_size=..., chunk_overlap=...).
2. If you have a custom splitter, make it subclass langchain TextSplitter (implement split_text).
3. Verify imports come from the same installed langchain/text-splitters package (pip show langchain; avoid multiple copies).

Example fix

// before
chunker = LangChainChunker(text_splitter=my_custom_split_fn, document_field='contents')

// after
from langchain_text_splitters import RecursiveCharacterTextSplitter
chunker = LangChainChunker(
    text_splitter=RecursiveCharacterTextSplitter(chunk_size=1000, chunk_overlap=100),
    document_field='contents')

def validate_splitter(splitter) -> bool:
    from langchain_text_splitters import TextSplitter
    if not isinstance(splitter, TextSplitter):
        raise TypeError('text_splitter must be a LangChain TextSplitter')
    return True

def is_text_splitter(obj) -> bool:
    try:
        from langchain_text_splitters import TextSplitter
        return isinstance(obj, TextSplitter)
    except ImportError:
        return False

try:
    chunker = LangChainChunker(text_splitter=splitter, document_field='contents')
except TypeError as e:
    logging.error('Bad splitter: %s (type=%s)', e, type(splitter).__name__)
    raise

When it happens

Trigger: Passing a non-TextSplitter object as text_splitter, e.g. a SemanticChunker, a plain function, a LangChain text_splitter from a different module namespace (langchain_text_splitters vs langchain.text_splitter in versions where the class identity differs), None when langchain is installed but the arg was omitted, or a custom splitter not subclassing TextSplitter.

Common situations: Using a splitter class imported from a different package than the one LangChainChunker imported (duplicate/mismatched langchain installs); passing a SentenceTransformerEmbeddings or other langchain object by mistake; custom splitter classes duck-typing the interface without inheriting TextSplitter.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Cannot specify both 'labels' and 'index'/'columns'
• num_splits must be greater than or equal 0
• source_file_names and destination_file_names should be equal
• Names must be a collection, not a string
• Namespaces must be an iterable, not a string

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