microsoft/graphrag · error · ValueError

api_key should not be set when using Azure Managed Identity.

Error message

api_key should not be set when using Azure Managed Identity.

What it means

ModelConfig validation forbids api_key when auth_method is AzureManagedIdentity. Managed Identity authenticates via the platform identity, so supplying a key is contradictory and usually means a stale key leaked into the config.

Source

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

    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

Unset the api_key / GRAPHRAG_API_KEY environment variable or remove api_key from settings.yaml when using Managed Identity
If you actually want key auth, set auth_method to APIKey instead

Example fix

# before
ModelConfig(auth_method=AuthMethod.AzureManagedIdentity, api_key=os.environ["API_KEY"])
# after
ModelConfig(auth_method=AuthMethod.AzureManagedIdentity)  # key removed, env var unset

Defensive patterns

Strategy: validation

Validate before calling

if auth_method == AuthMethod.AzureManagedIdentity:
    assert not api_key, "unset api_key before using Managed Identity"

Prevention

When switching to Managed Identity, unset GRAPHRAG_API_KEY/OPENAI_API_KEY in the environment and CI secrets
Add a startup assertion that api_key is None for managed-identity deployments

When it happens

Trigger: ModelConfig(auth_method=AuthMethod.AzureManagedIdentity, api_key="sk-...") or settings.yaml with both managed identity auth and an api_key entry/env var still set.

Common situations: Switching an Azure deployment from key auth to Managed Identity but leaving GRAPHRAG_API_KEY in the environment or settings file; the settings loader auto-populates api_key from env.

Related errors

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