What causes "api_key must be set when auth_method=api_key." in microsoft/graphrag?

Set the api_key directly or export the expected env var (e.g. GRAPHRAG_API_KEY / OPENAI_API_KEY) before constructing the config

microsoft/graphrag · error · ValueError

api_key must be set when auth_method=api_key.

Error message

api_key must be set when auth_method=api_key.

What it means

ModelConfig validation requires an api_key when auth_method defaults to (or is set to) APIKey. Without a key the LLM client cannot authenticate, so construction fails fast.

Source

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

    )

    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

Set the api_key directly or export the expected env var (e.g. GRAPHRAG_API_KEY / OPENAI_API_KEY) before constructing the config
For Azure Managed Identity or other keyless auth, set auth_method=AuthMethod.AzureManagedIdentity explicitly

Example fix

# before
ModelConfig(model_provider="openai", model="gpt-4o")  # ValueError: no key
# after
ModelConfig(model_provider="openai", model="gpt-4o", api_key=os.environ["OPENAI_API_KEY"])

Defensive patterns

Strategy: validation

Validate before calling

if auth_method == AuthMethod.APIKey and not os.environ.get("GRAPHRAG_API_KEY"):
    raise SystemExit("GRAPHRAG_API_KEY is not set; export it before running")

Try / catch

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

Prevention

Load .env early (python-dotenv) and fail fast on missing key vars
Name env vars consistently and document them in the project README
Add a smoke-test that constructs ModelConfig in CI to catch missing keys

When it happens

Trigger: ModelConfig(model_provider="openai", model="gpt-4o") with no api_key and auth_method=api_key (the default), typically because the API key env var is unset.

Common situations: Missing OPENAI_API_KEY / GRAPHRAG_API_KEY in the shell, CI, or container; typo'd env var name in .env; key present at deploy time but not in the local run environment.

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 microsoft/graphrag@f40e9a26ce (2026-08-27). Data as JSON: /api/errors/dfedf98860b47226. Report an issue: GitHub.