FoundationAgents/MetaGPT · critical · ValueError

Please set your API key in {root_config_path}. If you also s

Error message

Please set your API key in {root_config_path}. If you also set your config in {repo_config_path}, 
the former will overwrite the latter. This may cause unexpected result.

What it means

LLMConfig's api_key field validator rejects empty/None/'YOUR_API_KEY' keys. This variant fires when the global user config at CONFIG_ROOT/config2.yaml (~/.metagpt or METAGPT_CONFIG_PATH location) exists but still contains a placeholder/empty api_key; the long message also warns that the root config overrides the repo-level config/config2.yaml, which is a common double-config trap.

Source

Thrown at metagpt/configs/llm_config.py:123

    # Compress request messages under token limit
    compress_type: CompressType = CompressType.NO_COMPRESS

    # For Messages Control
    use_system_prompt: bool = True

    # 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. Open the root config path shown in the message and set a real api_key under the provider you use.
2. Remove or comment the api_key entry in the root config so the repo-level config2.yaml takes effect.
3. Alternatively supply the key programmatically: LLMConfig(api_key=os.environ['OPENAI_API_KEY']) or via environment variable if supported by your provider config.

Example fix

# before (~/.metagpt/config2.yaml)
openai:
  api_key: 'YOUR_API_KEY'

# after
openai:
  api_key: 'sk-...'

from metagpt.configs.llm_config import LLMConfig
cfg = LLMConfig.default()
assert cfg.api_key not in ('', None, 'YOUR_API_KEY'), 'set a real api_key before running'

When it happens

Trigger: Creating any LLM-backed component (LLM(), an Action with an LLM, starting the software-company flow) while CONFIG_ROOT/config2.yaml exists with api_key: '' or 'YOUR_API_KEY'. The root file takes precedence, so fixing only the repo copy does not help.

Common situations: Copying the shipped config2.yaml template to ~/.metagpt without filling the key; setting the key only in the repo config and being silently overridden; env var METAGPT_CONFIG_PATH pointing at an old template.

Related errors

• Please set your API key in {repo_config_path}
• Please set your API key in config2.yaml
• '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/cc62994b46046ebf. Report an issue: GitHub.