{"record":{"id":"7dc9d35d58815f44","repo":"datawhalechina/hello-agents","slug":"missing-required-environment-variables-missing-e","errorCode":null,"errorMessage":"Missing required environment variables: {missing_env_vars}. Create a .env file from .env.example or export them before running the project.","messagePattern":"Missing required environment variables: (.+?)\\. Create a \\.env file from \\.env\\.example or export them before running the project\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"critical","filePath":"Co-creation-projects/healer-666-Academic-Data-Agent/src/data_analysis_agent/config.py","lineNumber":83,"sourceCode":"        return _patched_get_encoding\n\n    hello_agents.context.token_counter.TokenCounter._get_encoding = _patched_get_encoding\n    _TOKEN_PATCH_APPLIED = True\n    return _patched_get_encoding\n\n\ndef load_runtime_config(env_file: Optional[str | Path] = None) -> RuntimeConfig:\n    \"\"\"Load and validate runtime configuration from the environment.\"\"\"\n\n    if env_file is not None:\n        load_dotenv(dotenv_path=env_file, override=False)\n    else:\n        load_dotenv(override=False)\n\n    required_env_vars = (\"LLM_MODEL_ID\", \"LLM_BASE_URL\", \"LLM_API_KEY\")\n    missing_env_vars = [name for name in required_env_vars if not os.getenv(name)]\n    if missing_env_vars:\n        raise ValueError(\n            \"Missing required environment variables: \"\n            + \", \".join(missing_env_vars)\n            + \". Create a .env file from .env.example or export them before running the project.\"\n        )\n\n    timeout = int(os.getenv(\"LLM_TIMEOUT\", \"120\"))\n    vision_timeout = int(os.getenv(\"VISION_LLM_TIMEOUT\", str(timeout)))\n    config = RuntimeConfig(\n        model_id=os.environ[\"LLM_MODEL_ID\"],\n        api_key=os.environ[\"LLM_API_KEY\"],\n        base_url=os.environ[\"LLM_BASE_URL\"],\n        timeout=timeout,\n        tavily_api_key=os.getenv(\"TAVILY_API_KEY\"),\n        vision_model_id=os.getenv(\"VISION_LLM_MODEL_ID\"),\n        vision_api_key=os.getenv(\"VISION_LLM_API_KEY\"),\n        vision_base_url=os.getenv(\"VISION_LLM_BASE_URL\"),\n        vision_timeout=vision_timeout,\n    )","sourceCodeStart":65,"sourceCodeEnd":101,"githubUrl":"https://github.com/datawhalechina/hello-agents/blob/606a07d341a47be773fab7f4b71177f53f96b2c3/Co-creation-projects/healer-666-Academic-Data-Agent/src/data_analysis_agent/config.py#L65-L101","documentation":"`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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\n# no .env, or only some vars set\n\n# after\n# .env\nLLM_MODEL_ID=gpt-4o-mini\nLLM_BASE_URL=https://api.example.com/v1\nLLM_API_KEY=sk-...","handlingStrategy":"validation","validationCode":"import os\n\nREQUIRED_LLM_VARS = (\"LLM_MODEL_ID\", \"LLM_BASE_URL\", \"LLM_API_KEY\")\n\ndef config_complete() -> bool:\n    return all(os.getenv(name) for name in REQUIRED_LLM_VARS)\n\n# fail with a clear message before importing/starting the agent\nfor name in REQUIRED_LLM_VARS:\n    assert os.getenv(name), f\"missing {name}; copy .env.example to .env and set it\"","typeGuard":null,"tryCatchPattern":"try:\n    cfg = load_runtime_config()\nexcept ValueError as e:\n    missing = [v for v in (\"LLM_MODEL_ID\", \"LLM_BASE_URL\", \"LLM_API_KEY\") if not os.getenv(v)]\n    print(f\"Fix .env: set {missing}. Original: {e}\")\n    raise SystemExit(1)","preventionTips":["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."],"tags":["configuration","env-vars","dotenv","startup","python"],"backgroundTag":null,"analyzedSha":"606a07d341a47be773fab7f4b71177f53f96b2c3","analyzedAt":"2026-08-14T22:57:27.446Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}