microsoft/graphrag · error · ValueError

azure_deployment_name should not be specified for non-Azure

Error message

azure_deployment_name should not be specified for non-Azure model providers.

What it means

ModelConfig validation rejects azure_deployment_name when model_provider is not 'azure'. The deployment name is only meaningful for Azure routing; specifying it with another provider indicates a mixed-up config.

Source

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

    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()
        return self

View on GitHub (pinned to f40e9a26ce)

Solutions

Remove the azure_deployment_name field from the config
Or, if you actually target Azure, set model_provider: azure (and provide api_base)

Example fix

# before
cfg = ModelConfig(model_provider="openai", model="gpt-4o", azure_deployment_name="deploy1")
# after
cfg = ModelConfig(model_provider="openai", model="gpt-4o")

Defensive patterns

Strategy: validation

Validate before calling

if cfg.get("azure_deployment_name") and cfg.get("model_provider") != "azure":
    cfg.pop("azure_deployment_name")  # or fail loudly
    # raise ValueError("azure_deployment_name set without azure provider")

Prevention

Keep provider-specific keys grouped in commented blocks in settings.yaml
Run a pre-flight script that strips/flags azure_* keys when provider != azure
Document which fields are azure-only in your project README

When it happens

Trigger: ModelConfig(model_provider="openai", azure_deployment_name="my-deployment") or a settings.yaml that sets azure_deployment_name while the provider was changed away from azure.

Common situations: Leftover azure_deployment_name after switching providers in settings.yaml; copying an Azure example config and only changing model_provider.

Related errors

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