apache/beam · error · ImportError

langchain is required to use LangChainChunkerPlease install

Error message

langchain is required to use LangChainChunkerPlease install it with using `pip install langchain`.

What it means

LangChainChunker.__init__ raises this ImportError when the langchain package is not importable in the environment. The module imports TextSplitter inside a try/except, leaving it as None on failure, and the constructor checks `if not TextSplitter` to fail fast with an actionable install hint rather than a confusing NameError later. LangChainChunker is an optional feature of the Beam RAG chunking library that delegates splitting to LangChain TextSplitters.

Source

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

      
      with beam.Pipeline() as p:
        chunks = (
            p 
            | 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,

View on GitHub (pinned to 12126d8942)

Solutions

1. Install the dependency: pip install langchain.
2. Add langchain to your requirements.txt / setup.py and pass it to Dataflow via --requirements_file so workers also get it.
3. If you don't need LangChain splitters, use a built-in chunker that has no langchain dependency.

Example fix

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

// after
# terminal: pip install langchain
chunker = LangChainChunker(text_splitter=RecursiveCharacterTextSplitter(...), document_field='contents')

import importlib.util

def langchain_available() -> bool:
    return importlib.util.find_spec('langchain') is not None

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

try:
    chunker = LangChainChunker(text_splitter=splitter, document_field='contents')
except ImportError:
    logging.error('Install langchain: pip install langchain')
    raise

When it happens

Trigger: Constructing LangChainChunker(text_splitter=..., document_field=...) in a Python environment where `pip install langchain` was never run, or in a deployment container/Docker image that does not include the langchain extra (apache_beam[gcp] alone does not pull it in).

Common situations: Deploying a Beam pipeline to Dataflow where extra packages were not passed via setup_file/requirements_file; running in a fresh venv or CI job missing the optional dependency;Beam installed without the ml/rag extras.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

• sentence-transformers is required to use HuggingfaceTextEmbe
• sentence-transformers is required to use HuggingfaceImageEmb
• Pillow is required to use HuggingfaceImageEmbeddings. Please
• vertexai is required to use VertexAITextEmbeddings. Please i
• text_splitter must be a LangChain TextSplitter

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