{"record":{"id":"cfed6222c16d766a","repo":"chroma-core/chroma","slug":"api-version-must-be-specified-for-azure-openai","errorCode":null,"errorMessage":"api_version must be specified for Azure OpenAI","messagePattern":"api_version must be specified for Azure OpenAI","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"chromadb/utils/embedding_functions/openai_embedding_function.py","lineNumber":95,"sourceCode":"        self.default_headers = default_headers\n        self.dimensions = dimensions\n\n        # Initialize the OpenAI client\n        client_params: Dict[str, Any] = {\"api_key\": self.api_key}\n\n        if self.organization_id is not None:\n            client_params[\"organization\"] = self.organization_id\n        if self.api_base is not None:\n            client_params[\"base_url\"] = self.api_base\n        if self.default_headers is not None:\n            client_params[\"default_headers\"] = self.default_headers\n\n        self.client = openai.OpenAI(**client_params)\n\n        # For Azure OpenAI\n        if self.api_type == \"azure\":\n            if self.api_version is None:\n                raise ValueError(\"api_version must be specified for Azure OpenAI\")\n            if self.deployment_id is None:\n                raise ValueError(\"deployment_id must be specified for Azure OpenAI\")\n            if self.api_base is None:\n                raise ValueError(\"api_base must be specified for Azure OpenAI\")\n\n            from openai import AzureOpenAI\n\n            self.client = AzureOpenAI(\n                api_key=self.api_key,\n                api_version=self.api_version,\n                azure_endpoint=self.api_base,\n                azure_deployment=self.deployment_id,\n                default_headers=self.default_headers,\n            )\n\n    def __call__(self, input: Documents) -> Embeddings:\n        \"\"\"\n        Generate embeddings for the given documents.","sourceCodeStart":77,"sourceCodeEnd":113,"githubUrl":"https://github.com/chroma-core/chroma/blob/aecdd12c8a891610db8653630b066b32ceb678b5/chromadb/utils/embedding_functions/openai_embedding_function.py#L77-L113","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nef = OpenAIEmbeddingFunction(\n    api_key=..., api_type=\"azure\",\n    deployment_id=\"text-embedding-3-small\",\n    api_base=\"https://myresource.openai.azure.com\",\n)  # ValueError: api_version must be specified for Azure OpenAI\n\n# after\nimport os\nazure_ef = OpenAIEmbeddingFunction(\n    api_key=os.environ[\"AZURE_OPENAI_API_KEY\"],\n    api_type=\"azure\",\n    api_version=\"2024-02-01\",\n    deployment_id=os.environ[\"AZURE_OPENAI_DEPLOYMENT\"],\n    api_base=os.environ[\"AZURE_OPENAI_ENDPOINT\"],\n)","handlingStrategy":"validation","validationCode":"def validate_azure_ef_config(cfg: dict) -> None:\n    missing = [k for k in (\"api_version\", \"deployment_id\", \"api_base\") if not cfg.get(k)]\n    if cfg.get(\"api_type\") == \"azure\" and missing:\n        raise RuntimeError(f\"Azure OpenAI config missing: {', '.join(missing)}\")\n\nvalidate_azure_ef_config({\"api_type\": \"azure\", \"api_version\": \"2024-02-01\", \"deployment_id\": \"d\", \"api_base\": \"https://x.openai.azure.com\"})","typeGuard":"def is_valid_azure_config(cfg: dict) -> bool:\n    return cfg.get(\"api_type\") != \"azure\" or all(\n        cfg.get(k) for k in (\"api_version\", \"deployment_id\", \"api_base\")\n    )","tryCatchPattern":"try:\n    ef = OpenAIEmbeddingFunction(**azure_cfg)\nexcept ValueError as e:\n    raise RuntimeError(f\"Invalid Azure OpenAI embedding config: {e}\") from e","preventionTips":["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."],"tags":["azure","openai","embedding","configuration","chroma","constructor"],"backgroundTag":"azure-openai-missing-config","analyzedSha":"aecdd12c8a891610db8653630b066b32ceb678b5","analyzedAt":"2026-08-16T21:53:27.228Z","schemaVersion":2},"datasetVersion":"2026-08-16T23:17:17.608Z"}