Please provide an Azure endpoint or set the environment vari

Error message

Please provide an Azure endpoint or set the environment variable AZURE_OPENAI_ENDPOINT.

What it means

AzureOpenAIDocumentEmbedder requires an Azure OpenAI endpoint. In __init__, the azure_endpoint parameter falls back to the AZURE_OPENAI_ENDPOINT environment variable; if both are absent, ValueError is raised. Without an endpoint, the Azure OpenAI client cannot be constructed.

Source

Thrown at haystack/components/embedders/azure_document_embedder.py:121

        :param max_retries: Maximum number of retries to contact AzureOpenAI after an internal error.
            If not set, defaults to either the `OPENAI_MAX_RETRIES` environment variable or to 5 retries.
        :param default_headers: Default headers to send to the AzureOpenAI client.
        :param azure_ad_token_provider: A function that returns an Azure Active Directory token, will be invoked on
            every request.
        :param http_client_kwargs:
            A dictionary of keyword arguments to configure a custom `httpx.Client`or `httpx.AsyncClient`.
            For more information, see the [HTTPX documentation](https://www.python-httpx.org/api/#client).
        :param raise_on_failure:
            Whether to raise an exception if the embedding request fails. If `False`, the component will log the error
            and continue processing the remaining documents. If `True`, it will raise an exception on failure.
        """
        # We intentionally do not call super().__init__ here because we only need to instantiate the client to interact
        # with the API.

        # if not provided as a parameter, azure_endpoint is read from the env var AZURE_OPENAI_ENDPOINT
        azure_endpoint = azure_endpoint or os.environ.get("AZURE_OPENAI_ENDPOINT")
        if not azure_endpoint:
            raise ValueError("Please provide an Azure endpoint or set the environment variable AZURE_OPENAI_ENDPOINT.")

        if api_key is None and azure_ad_token is None:
            raise ValueError("Please provide an API key or an Azure Active Directory token.")

        self.api_key = api_key  # type: ignore[assignment] # mypy does not understand that api_key can be None
        self.azure_ad_token = azure_ad_token
        self.api_version = api_version
        self.azure_endpoint = azure_endpoint
        self.azure_deployment = azure_deployment
        self.model = azure_deployment
        self.dimensions = dimensions
        self.organization = organization
        self.prefix = prefix
        self.suffix = suffix
        self.batch_size = batch_size
        self.progress_bar = progress_bar
        self.meta_fields_to_embed = meta_fields_to_embed or []
        self.embedding_separator = embedding_separator

View on GitHub (pinned to e318778c9b)

Solutions

Set the environment variable: export AZURE_OPENAI_ENDPOINT="https://<your-resource>.openai.azure.com/".
Or pass it explicitly: AzureOpenAIDocumentEmbedder(azure_endpoint="https://<your-resource>.openai.azure.com/").
If using a .env file, load it (python-dotenv) before instantiating the component.
Verify the variable is visible to the process (os.environ check) — shells, IDEs, and containers have different env scopes.

Example fix

# before
embedder = AzureOpenAIDocumentEmbedder()  # no endpoint anywhere
# after
import os
embedder = AzureOpenAIDocumentEmbedder(
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
    azure_deployment="my-embedding-deployment",
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
)

Defensive patterns

Strategy: validation

Validate before calling

import os

azure_endpoint = azure_endpoint or os.environ.get("AZURE_OPENAI_ENDPOINT")
if not azure_endpoint:
    raise ValueError(
        "Set AZURE_OPENAI_ENDPOINT or pass azure_endpoint to AzureOpenAIDocumentEmbedder"
    )

Try / catch

try:
    embedder = AzureOpenAIDocumentEmbedder(azure_endpoint=endpoint, api_key=key)
except ValueError as e:
    if "AZURE_OPENAI_ENDPOINT" in str(e):
        raise RuntimeError(
            "Deployment misconfiguration: AZURE_OPENAI_ENDPOINT missing. "
            "Check container/CI env vars and .env loading."
        ) from e
    raise

Prevention

Load .env files (python-dotenv) at application startup before building pipelines
Verify required env vars at process start with a fail-fast config check
In Docker/Kubernetes/CI, declare AZURE_OPENAI_ENDPOINT in the environment explicitly
Validate with: assert os.environ.get("AZURE_OPENAI_ENDPOINT"), 'missing endpoint'

When it happens

Trigger: Instantiating AzureOpenAIDocumentEmbedder() with no azure_endpoint argument while AZURE_OPENAI_ENDPOINT is unset or empty in the process environment.

Common situations: Env var defined in shell but not in the deployment/CI environment; using a `.env` file without loading it; running in Docker/Kubernetes without passing the variable; typo in the variable name.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of deepset-ai/haystack@e318778c9b (2026-08-30). Data as JSON: /api/errors/330509767a38c8b5. Report an issue: GitHub.