chroma-core/chroma · error · ValueError

Unsupported embedding function: {name}

Error message

Unsupported embedding function: {name}

What it means

After confirming the config has a "name" key, config_to_embedding_function looks that name up in known_embedding_functions — the registry of built-ins ("default", "openai", "cohere", "amazon_bedrock", "baseten", ...) plus anything registered via register_embedding_function in the current process. An unknown name raises this ValueError. Matching is exact and case-sensitive.

Source

Thrown at chromadb/utils/embedding_functions/__init__.py:259

    return _register


# Function to convert config to embedding function
def config_to_embedding_function(config: Dict[str, Any]) -> EmbeddingFunction:  # type: ignore
    """Convert a config dictionary to an embedding function.

    Args:
        config: The config dictionary.

    Returns:
        The embedding function.
    """
    if "name" not in config:
        raise ValueError("Config must contain a 'name' field.")

    name = config["name"]
    if name not in known_embedding_functions:
        raise ValueError(f"Unsupported embedding function: {name}")

    ef_config = config.get("config", {})

    if known_embedding_functions[name] is None:
        raise ValueError(f"Unsupported embedding function: {name}")

    validate_embedding_function_config_is_safe(name, ef_config)
    return known_embedding_functions[name].build_from_config(ef_config)


__all__ = [
    "EmbeddingFunction",
    "DefaultEmbeddingFunction",
    "CohereEmbeddingFunction",
    "OpenAIEmbeddingFunction",
    "BasetenEmbeddingFunction",
    "CloudflareWorkersAIEmbeddingFunction",
    "HuggingFaceEmbeddingFunction",

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Print the exact valid keys: from chromadb.utils.embedding_functions import known_embedding_functions; print(sorted(known_embedding_functions)) and use one verbatim.
2. If the name refers to a custom function, import and register it (register_embedding_function(MyEF)) before calling config_to_embedding_function.
3. Check casing, hyphens vs underscores, and version drift against the registry keys in the chromadb you actually run.

Example fix

# before: ValueError "Unsupported embedding function: my_ef"
ef = config_to_embedding_function({"name": "my_ef", "config": {}})

# after: register the custom class in this process first
from chromadb.utils.embedding_functions import register_embedding_function
register_embedding_function(MyEF)
ef = config_to_embedding_function({"name": "my_ef", "config": {}})

from chromadb.utils.embedding_functions import known_embedding_functions

def require_known_name(name: str) -> str:
    if name not in known_embedding_functions:
        available = ", ".join(sorted(known_embedding_functions))
        raise ValueError(f"Unknown EF '{name}'. Available: {available}")
    return name

ef = config_to_embedding_function({"name": require_known_name(cfg["name"]), "config": cfg.get("config", {})})

from chromadb.utils.embedding_functions import known_embedding_functions

def is_registered_ef_name(name: object) -> bool:
    return isinstance(name, str) and name in known_embedding_functions and known_embedding_functions[name] is not None

try:
    ef = config_to_embedding_function(cfg)
except ValueError as e:
    if "Unsupported embedding function" in str(e):
        register_embedding_function(MyEF)  # custom EFs must be registered in this process first
        ef = config_to_embedding_function(cfg)
    else:
        raise

When it happens

Trigger: config_to_embedding_function({"name": "OpenAI"}) (wrong case), {"name": "my_ef"} where the custom class was never registered in this process, or a name that existed in an older chromadb version but was renamed/removed.

Common situations: Custom EF registered in the writer process but not in the reader/server/worker that deserializes the collection; case or underscore mismatches ("sentence-transformer" vs "sentence_transformer"); configs produced against a different chromadb version.

Related errors

• Failed to register embedding function: {e}
• Failed to register sparse embedding function: {e}
• Config must contain a 'name' field.
• Keyword argument {key} is not a primitive type
• The model name cannot be changed after the embedding functio

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