datawhalechina/hello-agents · critical · ConfigurationError

LLM_API_KEY 仍是占位符，请在 .env 中填写真实密钥

Error message

LLM_API_KEY 仍是占位符，请在 .env 中填写真实密钥

What it means

Raised by LLMSettings validation when LLM_API_KEY still holds a known placeholder value. The check casefolds the key and rejects anything starting with 'your_' or exactly equal to 'changeme'/'replace_me'. This prevents shipping an app that authenticates with a template key and gets 401s from the provider.

Source

Thrown at Co-creation-projects/zenith191-RequirementClarifierAgent/src/config.py:76

        """拒绝缺失、占位符或越界配置。"""

        missing = [
            name
            for name, value in (
                ("LLM_MODEL_ID", self.model),
                ("LLM_API_KEY", self.api_key),
                ("LLM_BASE_URL", self.base_url),
            )
            if not value
        ]
        if missing:
            raise ConfigurationError(
                "缺少 LLM 配置：" + ", ".join(missing) + "。请先复制并填写 .env。"
            )

        lowered_key = self.api_key.casefold()
        if lowered_key.startswith("your_") or lowered_key in {"changeme", "replace_me"}:
            raise ConfigurationError("LLM_API_KEY 仍是占位符，请在 .env 中填写真实密钥")
        if not 0 <= self.temperature <= 2:
            raise ConfigurationError("LLM_TEMPERATURE 必须位于 0 到 2 之间")
        if self.timeout <= 0:
            raise ConfigurationError("LLM_TIMEOUT 必须大于 0")

View on GitHub (pinned to 606a07d341)

Solutions

1. Obtain a real API key from the provider and set LLM_API_KEY to it in .env.
2. Make sure you edited the .env actually loaded by the app (check cwd / dotenv path), not a stray copy.
3. If templating deployments, add a startup check or CI lint that fails builds still containing placeholder keys.

Example fix

# .env before
LLM_API_KEY=your_api_key_here

# .env after
LLM_API_KEY=sk-proj-xxxxxxxxxxxxxxxx

import os

key = os.getenv("LLM_API_KEY", "")
placeholders = {"changeme", "replace_me"}
if not key or key.casefold().startswith("your_") or key.casefold() in placeholders:
    raise SystemExit("LLM_API_KEY is unset or still a placeholder — set a real key")

try:
    settings = LLMSettings.from_env()
except ConfigurationError as e:
    if "占位符" in str(e):
        sys.exit("Fill in a real LLM_API_KEY before running")
    raise

When it happens

Trigger: Leaving LLM_API_KEY=your_api_key_here (or changeme / replace_me, any casing) in .env, then constructing the settings object.

Common situations: User copied .env.example verbatim and only filled in some fields; placeholder left in a deployed container's env; examples/templates reused as real config.

Related errors

• TMDB 未配置：请在 .env 设置 TMDB_ACCESS_TOKEN 或 TMDB_API_KEY
• TAVILY_API_KEY is required for TavilySearchTool
• 未配置 AMiner API Key。请前往 https://open.aminer.cn/ 注册获取，然后在 .env
• Unsupported latency_mode: {latency_mode}
• Unsupported vision_review_mode: {vision_review_mode}

AI-assisted analysis of datawhalechina/hello-agents@606a07d341 (2026-08-14). Data as JSON: /api/errors/3702baf4a6c2fc2b. Report an issue: GitHub.