{"record":{"id":"11dcb53a8292fb92","repo":"datawhalechina/hello-agents","slug":"e-11dcb5","errorCode":null,"errorMessage":"配置错误:\n  - {e}","messagePattern":"配置错误:\n  - (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"critical","filePath":"code/chapter13/helloagents-trip-planner/backend/app/config.py","lineNumber":84,"sourceCode":"\n\n# 验证必要的配置\ndef validate_config():\n    \"\"\"验证配置是否完整\"\"\"\n    errors = []\n    warnings = []\n\n    if not settings.amap_api_key:\n        errors.append(\"AMAP_API_KEY未配置\")\n\n    # HelloAgentsLLM会自动从LLM_API_KEY读取,不强制要求OPENAI_API_KEY\n    llm_api_key = os.getenv(\"LLM_API_KEY\") or os.getenv(\"OPENAI_API_KEY\")\n    if not llm_api_key:\n        warnings.append(\"LLM_API_KEY或OPENAI_API_KEY未配置,LLM功能可能无法使用\")\n\n    if errors:\n        error_msg = \"配置错误:\\n\" + \"\\n\".join(f\"  - {e}\" for e in errors)\n        raise ValueError(error_msg)\n\n    if warnings:\n        print(\"\\n⚠️  配置警告:\")\n        for w in warnings:\n            print(f\"  - {w}\")\n\n    return True\n\n\n# 打印配置信息(用于调试)\ndef print_config():\n    \"\"\"打印当前配置(隐藏敏感信息)\"\"\"\n    print(f\"应用名称: {settings.app_name}\")\n    print(f\"版本: {settings.app_version}\")\n    print(f\"服务器: {settings.host}:{settings.port}\")\n    print(f\"高德地图API Key: {'已配置' if settings.amap_api_key else '未配置'}\")\n\n    # 检查LLM配置","sourceCodeStart":66,"sourceCodeEnd":102,"githubUrl":"https://github.com/datawhalechina/hello-agents/blob/606a07d341a47be773fab7f4b71177f53f96b2c3/code/chapter13/helloagents-trip-planner/backend/app/config.py#L66-L102","documentation":"ValueError raised by the chapter13 backend's config validation when the errors list is non-empty — currently the only hard error is AMAP_API_KEY being unset. LLM keys only produce warnings. It fires at startup/import time of app.config, so a misconfigured backend refuses to boot with a bulleted message.","triggerScenarios":"Starting the FastAPI backend without AMAP_API_KEY in .env (or .env not loaded because the process was started from the wrong directory); AMAP_API_KEY set to an empty string; typos like AMAPKEY or AMAP_APIkey.","commonSituations":"Fresh clone without copying .env.example; running uvicorn from a directory where dotenv path resolution fails; CI/deploy env missing the secret; renaming the variable during refactoring.","solutions":["Create backend/.env with a valid AMAP_API_KEY=<your key> from console.amap.com","Start the backend from the backend/ directory (or fix the dotenv load path) so .env is actually read","Use the exact name AMAP_API_KEY; also add LLM_API_KEY to silence the warning and enable LLM features","Run the project's print_config()/validation before deploying to fail fast with readable output"],"exampleFix":"# before\n# backend/.env missing -> ValueError: 配置错误: - AMAP_API_KEY未配置\n\n# after\n# backend/.env\nAMAP_API_KEY=your-amap-key\nLLM_API_KEY=your-llm-key","handlingStrategy":"validation","validationCode":"import os\n\ndef backend_config_ready() -> bool:\n    return bool(os.getenv('AMAP_API_KEY'))\n\nif not backend_config_ready():\n    raise SystemExit('backend/.env must set AMAP_API_KEY before startup')","typeGuard":null,"tryCatchPattern":"try:\n    from app.config import validate_config\n    validate_config()\nexcept ValueError as e:\n    raise SystemExit(f'Fix backend configuration:\\n{e}')","preventionTips":["Copy .env.example to .env as the first setup step and keep it in sync","Run config validation in CI so missing keys fail the build, not production boot","Start uvicorn from the backend/ directory so relative .env loading works"],"tags":["configuration","environment-variables","startup","amap"],"backgroundTag":null,"analyzedSha":"606a07d341a47be773fab7f4b71177f53f96b2c3","analyzedAt":"2026-08-14T22:57:27.446Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}