What causes "缺少 LLM 配置：{missing}。请先复制并填写 .env。" in datawhalechina/hello-agents?

Copy the template: cp .env.example .env and fill in LLM_MODEL_ID, LLM_API_KEY, LLM_BASE_URL.

datawhalechina/hello-agents · critical · ConfigurationError

缺少 LLM 配置：{missing}。请先复制并填写 .env。

Error message

缺少 LLM 配置：{missing}。请先复制并填写 .env。

What it means

Raised by LLMSettings validation (src/config.py:70) when one or more of LLM_MODEL_ID, LLM_API_KEY, LLM_BASE_URL are empty/None. The message names the missing keys so you know exactly which required fields were not provided. It is a fail-fast guard meant to stop startup before an LLM client is constructed with unusable config.

Source

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

            timeout=_read_int("LLM_TIMEOUT", 120),
        )
        settings.validate()
        return settings

    def validate(self) -> None:
        """拒绝缺失、占位符或越界配置。"""

        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

Copy the template: cp .env.example .env and fill in LLM_MODEL_ID, LLM_API_KEY, LLM_BASE_URL.
Confirm the .env file is actually loaded at startup (dotenv.load_dotenv() called, correct path).
In CI, add the three variables as repository secrets/environment variables.
Re-run and confirm the missing list in the message is now empty.

Example fix

# before: .env missing
# (LLM_MODEL_ID not set at all)

# after: .env
LLM_MODEL_ID=gpt-4o-mini
LLM_API_KEY=sk-...
LLM_BASE_URL=https://api.openai.com/v1

Defensive patterns

Strategy: validation

Validate before calling

import os

REQUIRED = ("LLM_MODEL_ID", "LLM_API_KEY", "LLM_BASE_URL")
missing = [k for k in REQUIRED if not (os.getenv(k) or "").strip()]
if missing:
    raise SystemExit(f"Missing env: {', '.join(missing)} — copy .env.example to .env")

Try / catch

try:
    settings = LLMSettings.from_env()
except ConfigurationError as e:
    print(f"Setup incomplete: {e}")
    print("Run: cp .env.example .env && edit it")
    sys.exit(2)

Prevention

Ship a .env.example and a setup check in README step 1.
Add CI jobs that fail when required LLM_* vars are absent from the secret store.
Call dotenv.load_dotenv() explicitly with a resolved path at app entry.

When it happens

Trigger: Building LLMSettings (or calling from_env) with an empty-string api_key, a missing base_url, or before copying .env.example to .env. Any falsy value among the three required fields triggers it.

Common situations: Fresh clone without running the 'cp .env.example .env' step; .env exists but is not loaded (running from a different cwd, or python-dotenv not invoked); CI pipeline where secrets were never added; a key was commented out in .env.

Related errors

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