microsoft/graphrag · error · ValueError

api_base must be specified with the 'azure' model provider.

Error message

api_base must be specified with the 'azure' model provider.

What it means

Thrown by ModelConfig validation when model_provider is set to 'azure' but api_base is empty. LiteLLM's Azure backend requires an endpoint URL (e.g. https://<resource>.openai.azure.com) to route requests, so the config is rejected at construction time.

Source

Thrown at packages/graphrag-llm/graphrag_llm/config/model_config.py:92

        default=None,
        description="Configuration for the rate limit behavior.",
    )

    metrics: MetricsConfig | None = Field(
        default_factory=MetricsConfig,
        description="Specify and configure the metric services.",
    )

    mock_responses: list[str] | list[float] = Field(
        default_factory=list,
        description="List of mock responses for testing.",
    )

    def _validate_lite_llm_config(self) -> None:
        """Validate LiteLLM specific configuration."""
        if self.model_provider == "azure" and not self.api_base:
            msg = "api_base must be specified with the 'azure' model provider."
            raise ValueError(msg)

        if self.model_provider != "azure" and self.azure_deployment_name is not None:
            msg = "azure_deployment_name should not be specified for non-Azure model providers."
            raise ValueError(msg)

        if self.auth_method == AuthMethod.AzureManagedIdentity:
            if self.api_key is not None:
                msg = "api_key should not be set when using Azure Managed Identity."
                raise ValueError(msg)
        elif not self.api_key:
            msg = "api_key must be set when auth_method=api_key."
            raise ValueError(msg)

    @model_validator(mode="after")
    def _validate_model(self):
        """Validate model configuration after initialization."""
        if self.type == LLMProviderType.LiteLLM:
            self._validate_lite_llm_config()

View on GitHub (pinned to f40e9a26ce)

Solutions

1. Set api_base to your Azure OpenAI endpoint, e.g. api_base: "https://myresource.openai.azure.com" in settings or ModelConfig(api_base=...)
2. If the value comes from an env var, verify it is exported and picked up by the settings loader before constructing ModelConfig
3. If you did not intend Azure, change model_provider back to 'openai' (or another LiteLLM provider)

Example fix

# before
config = ModelConfig(model_provider="azure", model="gpt-4o", api_key="...")
# after
config = ModelConfig(model_provider="azure", model="gpt-4o", api_key="...", api_base="https://myresource.openai.azure.com")

provider = cfg.get("model_provider")
if provider == "azure" and not cfg.get("api_base"):
    raise SystemExit("azure provider requires api_base (https://<resource>.openai.azure.com)")

try:
    ModelConfig(**cfg)
except ValueError as e:
    if "api_base must be specified" in str(e):
        cfg["api_base"] = os.environ["AZURE_OPENAI_ENDPOINT"]
        model = ModelConfig(**cfg)
    else:
        raise

When it happens

Trigger: Creating a ModelConfig(model_provider="azure", ...) via Pydantic validation without an api_base field, or loading settings.yaml where azure is set but api_base is missing/None.

Common situations: Migrating from openai provider to azure and forgetting the endpoint; env var for api_base (e.g. GRAPHRAG_API_BASE) unset so the settings loader passes None; copy-pasted config missing the base URL.

Related errors

• azure_deployment_name should not be specified for non-Azure
• api_key should not be set when using Azure Managed Identity.
• model_id must be specified for LiteLLM tokenizer.
• api_key must be set when auth_method=api_key.
• period_in_seconds must be a positive integer for Sliding Win

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