deepset-ai/haystack · critical

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

AzureOpenAIDocumentEmbedder requires credentials: at least one of api_key or azure_ad_token must be provided (api_key may alternatively come from the AZURE_OPENAI_API_KEY env var per the Azure SDK). If both are None, ValueError is raised. The component intentionally skips super().__init__, so this validation happens explicitly in its __init__.

Source

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

        :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
        self.timeout = timeout
        self.max_retries = max_retries
        self.default_headers = default_headers or {}

View on GitHub (pinned to e318778c9b)

Solutions

  1. Provide api_key=<your Azure OpenAI key> (or ensure AZURE_OPENAI_API_KEY is set in the environment).
  2. Or pass azure_ad_token=<AAD token> for token-based auth; for managed identity consider using azure_ad_token generated via azure.identity DefaultAzureCredential.
  3. Verify the secret is actually injected in your runtime environment (CI variables, mounted secrets).

Example fix

# before
embedder = AzureOpenAIDocumentEmbedder(azure_endpoint=endpoint)  # no credentials
# after
import os
embedder = AzureOpenAIDocumentEmbedder(
    azure_endpoint=endpoint,
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
)
Defensive patterns

Strategy: validation

Validate before calling

import os

api_key = api_key or os.environ.get("AZURE_OPENAI_API_KEY")
if not api_key and not azure_ad_token:
    raise ValueError("Provide api_key or azure_ad_token for AzureOpenAIDocumentEmbedder")

Try / catch

try:
    embedder = AzureOpenAIDocumentEmbedder(azure_endpoint=endpoint, api_key=key)
except ValueError as e:
    if "API key" in str(e):
        raise RuntimeError("No Azure OpenAI credentials found; check AZURE_OPENAI_API_KEY or AAD token setup") from e
    raise

Prevention

When it happens

Trigger: Instantiating AzureOpenAIDocumentEmbedder() with neither api_key nor azure_ad_token arguments while AZURE_OPENAI_API_KEY is also unset in the environment.

Common situations: Switching to Azure AD/managed-identity auth but forgetting the token; new resource created but key not yet copied into secrets; CI/CD secrets not injected; deliberately omitting the key expecting an interactive prompt (none exists).

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/318bd247655c03ca. Report an issue: GitHub.