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

AzureOpenAITextEmbedder requires an Azure OpenAI endpoint. In __init__, the azure_endpoint argument falls back to the AZURE_OPENAI_ENDPOINT environment variable; if neither is set, ValueError is raised, because the underlying AzureOpenAI client mandates a non-None endpoint. This is the text-embedder sibling of the document embedder check.

Source

Thrown at haystack/components/embedders/azure_text_embedder.py:107

            A string to add at the end of each text.
        :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).

        """
        # We intentionally do not call super().__init__ here because we only need to instantiate the client to interact
        # with the API.

        # Why is this here?
        # AzureOpenAI init is forcing us to use an init method that takes either base_url or azure_endpoint as not
        # None init parameters. This way we accommodate the use case where env var AZURE_OPENAI_ENDPOINT is set instead
        # of passing it as a parameter.
        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.timeout = timeout
        self.max_retries = max_retries
        self.prefix = prefix
        self.suffix = suffix
        self.default_headers = default_headers or {}
        self.azure_ad_token_provider = azure_ad_token_provider

View on GitHub (pinned to e318778c9b)

Solutions

Set AZURE_OPENAI_ENDPOINT="https://<your-resource>.openai.azure.com/" in the environment, or pass azure_endpoint=... directly to the constructor.
Ensure the URL is the resource endpoint, not the deployment URL or a base_url.
Load your .env file before instantiating (python-dotenv) and confirm with os.environ.get("AZURE_OPENAI_ENDPOINT").

Example fix

# before
embedder = AzureOpenAITextEmbedder()  # ValueError
# after
embedder = AzureOpenAITextEmbedder(
    azure_endpoint="https://my-resource.openai.azure.com/",
    azure_deployment="text-embedding-ada-002",
    api_key="<key>",
)

Defensive patterns

Strategy: validation

Validate before calling

import os

endpoint = azure_endpoint or os.environ.get("AZURE_OPENAI_ENDPOINT")
if not endpoint:
    raise ValueError("Set AZURE_OPENAI_ENDPOINT or pass azure_endpoint to AzureOpenAITextEmbedder")
if not endpoint.startswith("https://"):
    raise ValueError("azure_endpoint must be the full resource URL, e.g. https://<resource>.openai.azure.com/")

Try / catch

try:
    embedder = AzureOpenAITextEmbedder(azure_endpoint=endpoint, api_key=key)
except ValueError as e:
    if "AZURE_OPENAI_ENDPOINT" in str(e):
        raise RuntimeError("Missing Azure endpoint; set AZURE_OPENAI_ENDPOINT or pass azure_endpoint explicitly") from e
    raise

Prevention

Set the endpoint env var in the same scope that launches the Python process
Load .env before importing/instantiating haystack components
Do not confuse azure_endpoint (resource URL) with azure_deployment (model deployment name)
Add a startup config validator that checks all required Azure env vars once at boot

When it happens

Trigger: Instantiating AzureOpenAITextEmbedder() with no azure_endpoint argument while AZURE_OPENAI_ENDPOINT is unset/empty in the environment.

Common situations: Env var not propagated to the runtime (Docker, serverless, CI); .env file not loaded; confusing AZURE_OPENAI_ENDPOINT with OPENAI_BASE_URL or an Azure deployment name (deployment goes to azure_deployment).

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/6645c0e5264e67c1. Report an issue: GitHub.