microsoft/autogen · critical · ImportError

Failed to create SentenceTransformer embedding function with

Error message

Failed to create SentenceTransformer embedding function with model '{config.model_name}'. Ensure sentence-transformers is installed and the model is available. Error: {e}

What it means

When the memory is configured with SentenceTransformerEmbeddingFunctionConfig, construction of the sentence-transformers embedding function is wrapped in a try/except; any failure (package missing, model download failure, model name typo) is re-raised as ImportError including the model name and the underlying error.

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/memory/chromadb/_chromadb.py:215

            ImportError: If required dependencies are not installed.
        """
        try:
            from chromadb.utils import embedding_functions
        except ImportError as e:
            raise ImportError(
                "ChromaDB embedding functions not available. Ensure chromadb is properly installed."
            ) from e

        config = self._config.embedding_function_config

        if isinstance(config, DefaultEmbeddingFunctionConfig):
            return embedding_functions.DefaultEmbeddingFunction()

        elif isinstance(config, SentenceTransformerEmbeddingFunctionConfig):
            try:
                return embedding_functions.SentenceTransformerEmbeddingFunction(model_name=config.model_name)
            except Exception as e:
                raise ImportError(
                    f"Failed to create SentenceTransformer embedding function with model '{config.model_name}'. "
                    f"Ensure sentence-transformers is installed and the model is available. Error: {e}"
                ) from e

        elif isinstance(config, OpenAIEmbeddingFunctionConfig):
            try:
                return embedding_functions.OpenAIEmbeddingFunction(api_key=config.api_key, model_name=config.model_name)
            except Exception as e:
                raise ImportError(
                    f"Failed to create OpenAI embedding function with model '{config.model_name}'. "
                    f"Ensure openai is installed and API key is valid. Error: {e}"
                ) from e

        elif isinstance(config, CustomEmbeddingFunctionConfig):
            try:
                return config.function(**config.params)
            except Exception as e:
                raise ValueError(f"Failed to create custom embedding function. Error: {e}") from e

View on GitHub (pinned to 027ecf0a37)

Solutions

Install sentence-transformers: pip install sentence-transformers.
Verify the exact model name exists on HuggingFace and matches what you passed.
In offline environments, pre-download the model (huggingface-cli download or set HF_HOME) and set HF_HUB_OFFLINE=1.
Read the trailing 'Error: {e}' in the message for the root cause (network vs missing module).

Example fix

# before
config = SentenceTransformerEmbeddingFunctionConfig(model_name="minilm")
# after
pip install sentence-transformers
config = SentenceTransformerEmbeddingFunctionConfig(model_name="sentence-transformers/all-MiniLM-L6-v2")

Defensive patterns

Strategy: try-catch

Validate before calling

try:
    import sentence_transformers  # noqa: F401
except ImportError:
    raise SystemExit("pip install sentence-transformers")
# optionally pre-download the model for offline use
# huggingface-cli download sentence-transformers/all-MiniLM-L6-v2

Try / catch

try:
    memory = ChromaDBVectorMemory(config=config_with_st)
except ImportError as e:
    if "SentenceTransformer" in str(e):
        # missing package, bad model name, or network failure — message carries Error: {cause}
        raise SystemExit(f"Fix embedding setup: {e}") from e
    raise

Prevention

Install sentence-transformers and pre-download models for offline/air-gapped runs.
Use fully qualified model ids (sentence-transformers/...).
Configure HF_HOME and proxies so model downloads succeed in restricted networks.

When it happens

Trigger: Configuring ChromaDBVectorMemory with SentenceTransformerEmbeddingFunctionConfig(model_name=...) and initializing it when sentence-transformers is not installed, the model name is invalid, or the machine cannot reach the HuggingFace hub to download the model.

Common situations: Offline/air-gapped environments; corporate proxies blocking huggingface.co; model name typos like 'all-MiniLM-L6-v2' vs 'sentence-transformers/all-MiniLM-L6-v2'; missing torch/onnxruntime.

Related errors

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/7de574dac0ebf610. Report an issue: GitHub.