datawhalechina/hello-agents · critical · ValueError

Missing required environment variables: {missing_env_vars}.

Error message

Missing required environment variables: {missing_env_vars}. Create a .env file from .env.example or export them before running the project.

What it means

`load_runtime_config` fails fast at startup/configuration load when any of the required env vars LLM_MODEL_ID, LLM_BASE_URL, LLM_API_KEY is missing or empty after `load_dotenv(override=False)`. The message lists exactly which vars are missing and instructs creating .env from .env.example.

Source

Thrown at Co-creation-projects/healer-666-Academic-Data-Agent/src/data_analysis_agent/config.py:83

        return _patched_get_encoding

    hello_agents.context.token_counter.TokenCounter._get_encoding = _patched_get_encoding
    _TOKEN_PATCH_APPLIED = True
    return _patched_get_encoding


def load_runtime_config(env_file: Optional[str | Path] = None) -> RuntimeConfig:
    """Load and validate runtime configuration from the environment."""

    if env_file is not None:
        load_dotenv(dotenv_path=env_file, override=False)
    else:
        load_dotenv(override=False)

    required_env_vars = ("LLM_MODEL_ID", "LLM_BASE_URL", "LLM_API_KEY")
    missing_env_vars = [name for name in required_env_vars if not os.getenv(name)]
    if missing_env_vars:
        raise ValueError(
            "Missing required environment variables: "
            + ", ".join(missing_env_vars)
            + ". Create a .env file from .env.example or export them before running the project."
        )

    timeout = int(os.getenv("LLM_TIMEOUT", "120"))
    vision_timeout = int(os.getenv("VISION_LLM_TIMEOUT", str(timeout)))
    config = RuntimeConfig(
        model_id=os.environ["LLM_MODEL_ID"],
        api_key=os.environ["LLM_API_KEY"],
        base_url=os.environ["LLM_BASE_URL"],
        timeout=timeout,
        tavily_api_key=os.getenv("TAVILY_API_KEY"),
        vision_model_id=os.getenv("VISION_LLM_MODEL_ID"),
        vision_api_key=os.getenv("VISION_LLM_API_KEY"),
        vision_base_url=os.getenv("VISION_LLM_BASE_URL"),
        vision_timeout=vision_timeout,
    )

View on GitHub (pinned to 606a07d341)

Solutions

Create .env from .env.example and fill in LLM_MODEL_ID, LLM_BASE_URL, LLM_API_KEY.
Ensure the process's working directory contains .env or pass env_file explicitly to load_runtime_config.
Unset any empty exported vars that shadow .env values (`env | grep LLM_` to inspect).
For Docker/systemd, inject the three vars through the environment instead of relying on a copied .env.

Example fix

// before
# no .env, or only some vars set

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

Defensive patterns

Strategy: validation

Validate before calling

import os

REQUIRED_LLM_VARS = ("LLM_MODEL_ID", "LLM_BASE_URL", "LLM_API_KEY")

def config_complete() -> bool:
    return all(os.getenv(name) for name in REQUIRED_LLM_VARS)

# fail with a clear message before importing/starting the agent
for name in REQUIRED_LLM_VARS:
    assert os.getenv(name), f"missing {name}; copy .env.example to .env and set it"

Try / catch

try:
    cfg = load_runtime_config()
except ValueError as e:
    missing = [v for v in ("LLM_MODEL_ID", "LLM_BASE_URL", "LLM_API_KEY") if not os.getenv(v)]
    print(f"Fix .env: set {missing}. Original: {e}")
    raise SystemExit(1)

Prevention

Copy .env.example → .env as the first setup step and fill all LLM_* vars.
Remember override=False: exported empty vars shadow .env — unset stale ones.
Add a config preflight (docker entrypoint, CI job) that fails fast on missing vars.

When it happens

Trigger: Running the data-analysis agent without a .env file; a .env that defines only some of the three vars; real environment vars take precedence over .env (override=False) so an empty exported var shadows a populated .env line; server started from a directory where python-dotenv cannot find .env.

Common situations: Fresh clone without copying .env.example → .env; CI/containers that don't inject the vars; deploying with an env var set to empty string (e.g. `LLM_API_KEY=` in the compose file) which blanks the .env value.

Related errors

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