FoundationAgents/MetaGPT · critical · ValueError

Please set your API key in config2.yaml

Error message

Please set your API key in config2.yaml

What it means

The fallback branch of LLMConfig.check_llm_key: the api_key is empty/placeholder and neither the root config (~/.metagpt/config2.yaml) nor the repo config (metagpt/config/config2.yaml) exists at all, so the validator has no file to point at and tells you to create config2.yaml. Any LLM construction will fail until a config with a valid key is provided.

Source

Thrown at metagpt/configs/llm_config.py:130

    # reasoning / thinking switch
    reasoning: bool = False
    reasoning_max_token: int = 4000  # reasoning budget tokens to generate, usually smaller than max_token

    @field_validator("api_key")
    @classmethod
    def check_llm_key(cls, v):
        if v in ["", None, "YOUR_API_KEY"]:
            repo_config_path = METAGPT_ROOT / "config/config2.yaml"
            root_config_path = CONFIG_ROOT / "config2.yaml"
            if root_config_path.exists():
                raise ValueError(
                    f"Please set your API key in {root_config_path}. If you also set your config in {repo_config_path}, \n"
                    f"the former will overwrite the latter. This may cause unexpected result.\n"
                )
            elif repo_config_path.exists():
                raise ValueError(f"Please set your API key in {repo_config_path}")
            else:
                raise ValueError("Please set your API key in config2.yaml")
        return v

    @field_validator("timeout")
    @classmethod
    def check_timeout(cls, v):
        return v or LLM_API_TIMEOUT

View on GitHub (pinned to 11cdf466d0)

Solutions

1. Copy the template: cp metagpt/config/config2.yaml ~/.metagpt/config2.yaml (or keep it in-repo) and set api_key.
2. Or construct config in code: LLM.from_llm_config(LLMConfig(api_key='sk-...', base_url=..., model=...)).
3. In CI, write the config from a secret env var before starting MetaGPT.

Example fix

# before
from metagpt.llm import LLM
llm = LLM()  # ValueError: Please set your API key in config2.yaml

# after
from metagpt.configs.llm_config import LLMConfig
llm = LLM(LLMConfig(api_key='sk-...', model='gpt-4o-mini'))

import os
assert os.environ.get('OPENAI_API_KEY'), 'set OPENAI_API_KEY or create config2.yaml'
# then either export the env var your provider block reads, or write the config:
# ~/.metagpt/config2.yaml with a valid api_key

When it happens

Trigger: Running any LLM call in an environment where config2.yaml was never created (no template copied, no user config), and no api_key supplied via code or environment.

Common situations: New installs where the setup step (copying config2.yaml) was skipped; Docker/CI images that never bake a config; library usage where the caller assumed defaults work without a key.

Related errors

• Please set your API key in {root_config_path}. If you also s
• Please set your API key in {repo_config_path}
• 'model' parameter is required
• Model '{model}' not found in configuration
• use `revise` after `fill`

AI-assisted analysis of FoundationAgents/MetaGPT@11cdf466d0 (2026-08-14). Data as JSON: /api/errors/9d93233d73f995cd. Report an issue: GitHub.