What causes "api_version must be specified for Azure OpenAI" in chroma-core/chroma?

Pass an explicit Azure API version: OpenAIEmbeddingFunction(api_type="azure", api_version="2024-02-01", deployment_id=..., api_base=..., api_key=...).

chroma-core/chroma · error · ValueError

api_version must be specified for Azure OpenAI

Error message

api_version must be specified for Azure OpenAI

What it means

When OpenAIEmbeddingFunction is configured with api_type="azure", the constructor validates that the Azure-specific trio (api_version, deployment_id, api_base) is present. This specific ValueError fires when api_version is None: the AzureOpenAI client cannot be built without an API version because Azure OpenAI endpoints are versioned (e.g. "2024-02-01"). The check happens in __init__, right after a default openai.OpenAI client was created, before the Azure client replaces it.

Source

Thrown at chromadb/utils/embedding_functions/openai_embedding_function.py:95

        self.default_headers = default_headers
        self.dimensions = dimensions

        # Initialize the OpenAI client
        client_params: Dict[str, Any] = {"api_key": self.api_key}

        if self.organization_id is not None:
            client_params["organization"] = self.organization_id
        if self.api_base is not None:
            client_params["base_url"] = self.api_base
        if self.default_headers is not None:
            client_params["default_headers"] = self.default_headers

        self.client = openai.OpenAI(**client_params)

        # For Azure OpenAI
        if self.api_type == "azure":
            if self.api_version is None:
                raise ValueError("api_version must be specified for Azure OpenAI")
            if self.deployment_id is None:
                raise ValueError("deployment_id must be specified for Azure OpenAI")
            if self.api_base is None:
                raise ValueError("api_base must be specified for Azure OpenAI")

            from openai import AzureOpenAI

            self.client = AzureOpenAI(
                api_key=self.api_key,
                api_version=self.api_version,
                azure_endpoint=self.api_base,
                azure_deployment=self.deployment_id,
                default_headers=self.default_headers,
            )

    def __call__(self, input: Documents) -> Embeddings:
        """
        Generate embeddings for the given documents.

View on GitHub (pinned to aecdd12c8a)

Solutions

Pass an explicit Azure API version: OpenAIEmbeddingFunction(api_type="azure", api_version="2024-02-01", deployment_id=..., api_base=..., api_key=...).
Find the supported versions in Azure Portal under your deployment (Playground -> code sample shows the api_version string), or use the Azure OpenAI REST API reference for your region.
Centralize the trio in env vars (AZURE_OPENAI_API_VERSION, AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_DEPLOYMENT) and read them so the same code works across dev/prod.
Double-check spelling of the kwarg: it is api_version (API path version), not the model name and not deployment_id.

Example fix

// before
ef = OpenAIEmbeddingFunction(
    api_key=..., api_type="azure",
    deployment_id="text-embedding-3-small",
    api_base="https://myresource.openai.azure.com",
)  # ValueError: api_version must be specified for Azure OpenAI

# after
import os
azure_ef = OpenAIEmbeddingFunction(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    api_type="azure",
    api_version="2024-02-01",
    deployment_id=os.environ["AZURE_OPENAI_DEPLOYMENT"],
    api_base=os.environ["AZURE_OPENAI_ENDPOINT"],
)

Defensive patterns

Strategy: validation

Validate before calling

def validate_azure_ef_config(cfg: dict) -> None:
    missing = [k for k in ("api_version", "deployment_id", "api_base") if not cfg.get(k)]
    if cfg.get("api_type") == "azure" and missing:
        raise RuntimeError(f"Azure OpenAI config missing: {', '.join(missing)}")

validate_azure_ef_config({"api_type": "azure", "api_version": "2024-02-01", "deployment_id": "d", "api_base": "https://x.openai.azure.com"})

Type guard

def is_valid_azure_config(cfg: dict) -> bool:
    return cfg.get("api_type") != "azure" or all(
        cfg.get(k) for k in ("api_version", "deployment_id", "api_base")
    )

Try / catch

try:
    ef = OpenAIEmbeddingFunction(**azure_cfg)
except ValueError as e:
    raise RuntimeError(f"Invalid Azure OpenAI embedding config: {e}") from e

Prevention

Keep api_version, deployment_id, api_base together in one config struct/env group so they are never partially passed.
Add a startup config schema check (pydantic model with required fields when api_type == 'azure').
Copy the exact endpoint, deployment name, and api_version from the Azure Portal code-sample snippet to avoid transcription drift.
Pin api_version explicitly instead of relying on defaults; Azure deprecates versions over time.

When it happens

Trigger: OpenAIEmbeddingFunction(api_type="azure", ...) without api_version. Typical call: OpenAIEmbeddingFunction(api_key=..., api_type="azure", api_base="https://<resource>.openai.azure.com", deployment_id="my-deploy") — still fails because api_version was omitted. Copying an OpenAI-compatibility example that only sets api_base also triggers it once api_type="azure" is added.

Common situations: Migrating from public OpenAI to Azure OpenAI and assuming base_url+key is enough; confusing deployment model names with API versions; using an out-of-date tutorial that predates the required api_version parameter; environment-specific config where the API version key name in a YAML/JSON config doesn't match the constructor kwarg.

Related errors

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