chroma-core/chroma · error · ValueError

api_base must be specified for Azure OpenAI

Error message

api_base must be specified for Azure OpenAI

What it means

Third of the Azure validation checks in OpenAIEmbeddingFunction.__init__: with api_type="azure", api_base must be provided. api_base becomes AzureOpenAI(azure_endpoint=...) — the HTTPS endpoint of your Azure OpenAI resource (e.g. https://<resource-name>.openai.azure.com). Without it the client has no endpoint to send requests to, so construction fails even though api_version and deployment_id may already be correct.

Source

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

        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.
        Returns:
            Embeddings for the documents.

View on GitHub (pinned to aecdd12c8a)

Solutions

1. Pass the full resource endpoint: api_base="https://<your-resource-name>.openai.azure.com" — find it in Azure Portal under your Azure OpenAI resource -> Keys and Endpoint.
2. Prefer loading from env: api_base=os.environ["AZURE_OPENAI_ENDPOINT"] and set AZURE_OPENAI_ENDPOINT in your deployment secrets.
3. Include the scheme (https://) — a bare hostname or resource name is not a valid endpoint.
4. Keep all three Azure values (api_base, api_version, deployment_id) in one config object so they are passed together.

Example fix

// before
azure_ef = OpenAIEmbeddingFunction(
    api_type="azure", api_version="2024-02-01",
    deployment_id="my-embed-deployment",
)  # ValueError: api_base must be specified for Azure OpenAI

# after
azure_ef = OpenAIEmbeddingFunction(
    api_type="azure", api_version="2024-02-01",
    deployment_id="my-embed-deployment",
    api_base=os.environ["AZURE_OPENAI_ENDPOINT"],  # https://myresource.openai.azure.com
)

endpoint = os.getenv("AZURE_OPENAI_ENDPOINT", "")
if not endpoint.startswith("https://") or not endpoint.endswith(".openai.azure.com"):
    raise RuntimeError(
        f"AZURE_OPENAI_ENDPOINT must look like https://<resource>.openai.azure.com, got: {endpoint!r}"
    )

def is_azure_endpoint(value: str) -> bool:
    return value.startswith("https://") and ".openai.azure.com" in value

try:
    azure_ef = OpenAIEmbeddingFunction(api_type="azure", api_base=endpoint, api_version=v, deployment_id=d)
except ValueError as e:
    raise RuntimeError(f"Azure embedding setup incomplete: {e}") from e

When it happens

Trigger: OpenAIEmbeddingFunction(api_type="azure", api_version=..., deployment_id=...) with api_base omitted. Also triggered when the endpoint is stored in a differently-named setting (e.g. AZURE_OPENAI_ENDPOINT vs OPENAI_API_BASE) and never forwarded to the constructor.

Common situations: Copying the endpoint from the wrong portal blade (keys/endpoints page) or pasting only the resource name; config-driven setups where the endpoint key exists in the YAML but is read into a variable that is never passed; migrating code that previously used openai.api_base for the public API.

Related errors

• api_version must be specified for Azure OpenAI
• deployment_id must be specified for Azure OpenAI
• The {self.api_key_env_var} environment variable is not set.
• The model name cannot be changed after the embedding functio
• OpenAI API key is required. Please provide it in the constru

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