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

Create (or locate) a deployment in Azure Portal -> your Azure OpenAI resource -> Model deployments, then pass its exact name: OpenAIEmbeddingFunction(api_type="azure", deployment_id=" ", api_version=..., api_base=...).

chroma-core/chroma · error · ValueError

deployment_id must be specified for Azure OpenAI

Error message

deployment_id must be specified for Azure OpenAI

What it means

Azure validation in OpenAIEmbeddingFunction.__init__: with api_type="azure", deployment_id must be set. Azure OpenAI does not address models by plain model name; embeddings are served from a named deployment you created in the portal/CLI, and it maps to AzureOpenAI(azure_deployment=...). A None deployment_id therefore means the client cannot know which deployment to call, so the constructor raises immediately.

Source

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

        # 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.
        Args:
            input: Documents to generate embeddings for.

View on GitHub (pinned to aecdd12c8a)

Solutions

Create (or locate) a deployment in Azure Portal -> your Azure OpenAI resource -> Model deployments, then pass its exact name: OpenAIEmbeddingFunction(api_type="azure", deployment_id="<deployment-name>", api_version=..., api_base=...).
Use Azure CLI to create one if missing: az cognitiveservices account deployment create --resource-group <rg> --name <account> --deployment-name embed-dep --model-name text-embedding-3-small --model-version latest --model-format OpenAI.
Load it from configuration/env (AZURE_OPENAI_DEPLOYMENT) so local and cloud values don't get mixed up.
Remember model_name stays as the underlying model (e.g. text-embedding-3-small) while deployment_id is the deployment you named — both are needed.

Example fix

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

# after
azure_ef = OpenAIEmbeddingFunction(
    api_type="azure", api_version="2024-02-01",
    api_base="https://myresource.openai.azure.com",
    model_name="text-embedding-3-small",
    deployment_id="my-embed-deployment",  # deployment name from Azure Portal
)

Defensive patterns

Strategy: validation

Validate before calling

AZURE_REQUIRED = ("api_base", "api_version", "deployment_id")
missing = [k for k in AZURE_REQUIRED if not os.getenv(f"AZURE_OPENAI_{k.upper()}")]
if missing:
    raise RuntimeError(f"Set these before startup: {', '.join('AZURE_OPENAI_' + m.upper() for m in missing)}")

Type guard

def azure_config_complete(cfg: dict) -> bool:
    return all(cfg.get(k) for k in ("api_version", "deployment_id", "api_base"))

Try / catch

try:
    azure_ef = OpenAIEmbeddingFunction(api_type="azure", **azure_params)
except ValueError as e:
    # e.g. "deployment_id must be specified for Azure OpenAI"
    raise RuntimeError(f"Fix Azure OpenAI settings: {e}") from e

Prevention

Create the model deployment before wiring code, and store its exact name in AZURE_OPENAI_DEPLOYMENT.
Never assume model_name selects the Azure target — deployment_id is the addressing key.
Validate the whole Azure trio at config load time, not at first embed.
Use a pydantic/settings model so missing required fields fail fast with field-level messages.

When it happens

Trigger: OpenAIEmbeddingFunction(api_type="azure", api_version=..., api_base=...) with deployment_id omitted. A frequent variant: passing model_name="text-embedding-ada-002" believing it selects the Azure target — it does not; only deployment_id does, so the error still fires.

Common situations: New Azure OpenAI resource where the developer has the model name but no deployment yet (deployments must be created explicitly); multiple deployments and the wrong variable copied; confusion between deployment name and model name — the deployment can be named anything and is what must be passed.

Related errors

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