Please provide an API key or an Azure Active Directory token

Error message

Please provide an API key or an Azure Active Directory token.

What it means

AzureTextEmbedder requires credentials to construct an Azure OpenAI client. The constructor raises this ValueError when neither an `api_key` nor an `azure_ad_token` is provided, because the underlying Azure SDK client cannot authenticate without one of them. Note the message says 'API key or Azure Active Directory token' — passing only an endpoint and deployment is not enough.

Source

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

            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
        self.http_client_kwargs = http_client_kwargs

        self.client: AzureOpenAI | None = None

View on GitHub (pinned to e318778c9b)

Solutions

Pass `api_key="..."` to the constructor
Or pass `azure_ad_token="..."` for Azure Active Directory authentication
Or set the AZURE_OPENAI_API_KEY environment variable, which the default init parameter reads
Verify the credential is actually present in the runtime environment (print/debug os.environ in the failing context)

Example fix

// before
embedder = AzureTextEmbedder(azure_endpoint="https://myres.openai.azure.com", azure_deployment="my-deployment")
// after
embedder = AzureTextEmbedder(azure_endpoint="https://myres.openai.azure.com", azure_deployment="my-deployment", api_key=os.environ["AZURE_OPENAI_API_KEY"])

Defensive patterns

Strategy: validation

Validate before calling

import os
assert (os.environ.get("AZURE_OPENAI_API_KEY") or api_key or azure_ad_token), "Provide api_key, azure_ad_token, or set AZURE_OPENAI_API_KEY"
embedder = AzureTextEmbedder(api_key=api_key, azure_ad_token=azure_ad_token)

Type guard

def has_azure_credentials(api_key=None, azure_ad_token=None) -> bool:
    return bool(api_key or azure_ad_token or os.environ.get("AZURE_OPENAI_API_KEY"))

Prevention

Store AZURE_OPENAI_API_KEY in the deployment environment's secret manager
Assert credentials exist in test setup before constructing Azure components
Prefer env-var configuration so the same code works locally and in CI

When it happens

Trigger: Calling `AzureTextEmbedder(azure_endpoint=..., azure_deployment=...)` with both `api_key` and `azure_ad_token` left as None and no usable credential resolved.

Common situations: Deploying to an environment where the `AZURE_OPENAI_API_KEY` env var is not set; forgetting to pass the key after switching from the plain OpenAI embedder to the Azure variant; intending to use Entra ID auth but not supplying the token; keys defined in a different environment (e.g. CI secrets not injected).

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

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