microsoft/graphrag · error · ValueError

url must be provided for Azure AI Search.

Error message

url must be provided for Azure AI Search.

What it means

The Azure AI Search vector store adapter requires the service endpoint URL (https://<service>.search.windows.net) to construct any index client; there is no default or discovery mechanism. __init__ validates url right after super() so it fails before connect().

Source

Thrown at packages/graphrag-vectors/graphrag_vectors/azure_ai_search.py:64

class AzureAISearchVectorStore(VectorStore):
    """Azure AI Search vector storage implementation."""

    index_client: SearchIndexClient

    def __init__(
        self,
        url: str,
        api_key: str | None = None,
        audience: str | None = None,
        vector_search_profile_name: str = "vectorSearchProfile",
        **kwargs: Any,
    ):
        super().__init__(**kwargs)
        if not url:
            msg = "url must be provided for Azure AI Search."
            raise ValueError(msg)
        self.url = url
        self.api_key = api_key
        self.audience = audience
        self.vector_search_profile_name = vector_search_profile_name

    def connect(self) -> Any:
        """Connect to AI search vector storage."""
        audience_arg = (
            {"audience": self.audience} if self.audience and not self.api_key else {}
        )
        self.db_connection = SearchClient(
            endpoint=self.url,
            index_name=self.index_name,
            credential=(
                AzureKeyCredential(self.api_key)
                if self.api_key
                else DefaultAzureCredential()
            ),

View on GitHub (pinned to f40e9a26ce)

Solutions

1. Set url in the vector store config or its env var (e.g. AZURE_AI_SEARCH_URL=https://mysearch.search.windows.net)
2. Verify the env var is present in the executing environment (print it before init)
3. Use the full endpoint including https:// and .search.windows.net

Example fix

# before
AzureAISearch(api_key=key)
# after
AzureAISearch(url="https://mysearch.search.windows.net", api_key=key)

import os
url = os.environ.get("AZURE_AI_SEARCH_URL")
assert url, "set AZURE_AI_SEARCH_URL before init"

When it happens

Trigger: Instantiating AzureAISearch (or configuring vector storage type azure_ai_search) without url — missing AZURE_AI_SEARCH_URL env var or omitted YAML key.

Common situations: Env var not injected in deployment; YAML key named endpoint instead of url; secrets template copied incompletely.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• Unsupported filter expression type: {type(expr)}
• Unsupported operator for Azure AI Search: {cond.operator}
• CosmosDB requires the id_field to be 'id'.
• Either connection_string or url must be provided for CosmosD
• api_key must be set when auth_method=api_key.

AI-assisted analysis of microsoft/graphrag@f40e9a26ce (2026-08-27). Data as JSON: /api/errors/d22428f124e0418c. Report an issue: GitHub.