chroma-core/chroma · error · ValueError

The embedding_function must implement the Embeddings interfa

Error message

The embedding_function must implement the Embeddings interface from langchain_core.

What it means

After importing langchain_core, the constructor asserts isinstance(embedding_function, langchain_core.embeddings.Embeddings) and raises ValueError otherwise. The adapter delegates to embed_documents/embed_query, so the wrapped object must be a real Embeddings instance — a bare callable or unrelated object will break every later call.

Source

Thrown at chromadb/utils/embedding_functions/chroma_langchain_embedding_function.py:51

    def __init__(self, embedding_function: Any) -> None:
        """
        Initialize the ChromaLangchainEmbeddingFunction

        Args:
            embedding_function: The embedding function implementing Embeddings from langchain_core.
        """
        try:
            import langchain_core.embeddings

            LangchainEmbeddings = langchain_core.embeddings.Embeddings
        except ImportError:
            raise ValueError(
                "The langchain_core python package is not installed. Please install it with `pip install langchain-core`"
            )

        if not isinstance(embedding_function, LangchainEmbeddings):
            raise ValueError(
                "The embedding_function must implement the Embeddings interface from langchain_core."
            )

        self.embedding_function = embedding_function

        # Store the class name for serialization
        self._embedding_function_class = embedding_function.__class__.__name__

    def embed_documents(self, documents: Sequence[str]) -> List[List[float]]:
        """
        Embed documents using the langchain embedding function.

        Args:
            documents: The documents to embed.

        Returns:
            The embeddings for the documents.
        """

View on GitHub (pinned to aecdd12c8a)

Solutions

Wrap a genuine langchain embeddings class, e.g. from langchain_openai import OpenAIEmbeddings; create_langchain_embedding(OpenAIEmbeddings(...)).
If you have a custom function, expose it as a class subclassing langchain_core.embeddings.Embeddings implementing embed_documents and embed_query.
For chromadb-native functions, skip the bridge and pass them to the collection directly.
Unify on one langchain-core version to avoid ABC identity mismatches.

Example fix

# before
from openai import OpenAI
client = OpenAI()
ef = create_langchain_embedding(client.embeddings)  # ValueError: not an Embeddings instance

# after
from langchain_openai import OpenAIEmbeddings
ef = create_langchain_embedding(OpenAIEmbeddings(model="text-embedding-3-large"))

Defensive patterns

Strategy: type-guard

Validate before calling

from langchain_core.embeddings import Embeddings

if not isinstance(my_embeddings, Embeddings):
    raise TypeError(f"Expected langchain_core Embeddings, got {type(my_embeddings).__name__}")
ef = create_langchain_embedding(my_embeddings)

Type guard

from langchain_core.embeddings import Embeddings

def is_langchain_embeddings(obj: object) -> bool:
    """True when obj can be wrapped by ChromaLangchainEmbeddingFunction."""
    return isinstance(obj, Embeddings)

Try / catch

try:
    ef = create_langchain_embedding(candidate)
except ValueError as e:
    if "must implement the Embeddings interface" in str(e):
        raise TypeError(f"Wrap a langchain Embeddings class, not {type(candidate)}") from e
    raise

Prevention

Always wrap classes from langchain provider packages (langchain_openai, langchain_huggingface), never raw SDK clients.
For custom logic, subclass langchain_core.embeddings.Embeddings with embed_documents and embed_query.
Guard construction sites with an isinstance check against langchain_core's Embeddings.

When it happens

Trigger: Passing anything that is not a langchain_core Embeddings subclass: a plain function, an OpenAI/other SDK client object, a chromadb EmbeddingFunction, or a duck-typed object from an incompatible langchain-core version where the ABC identity differs.

Common situations: Wrapping the raw OpenAI Python client instead of langchain_openai.OpenAIEmbeddings; passing chromadb's own embedding functions into the langchain bridge; multiple langchain-core versions in one process (conda + pip mix) making isinstance fail despite matching shape.

Related errors

AI-assisted analysis of chroma-core/chroma@aecdd12c8a (2026-08-16). Data as JSON: /api/errors/6103d6ffffbf2678. Report an issue: GitHub.