datawhalechina/hello-agents · critical · ValueError

配置错误: - {e}

Error message

配置错误:
  - {e}

What it means

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.

Source

Thrown at code/chapter13/helloagents-trip-planner/backend/app/config.py:84

# 验证必要的配置
def validate_config():
    """验证配置是否完整"""
    errors = []
    warnings = []

    if not settings.amap_api_key:
        errors.append("AMAP_API_KEY未配置")

    # HelloAgentsLLM会自动从LLM_API_KEY读取,不强制要求OPENAI_API_KEY
    llm_api_key = os.getenv("LLM_API_KEY") or os.getenv("OPENAI_API_KEY")
    if not llm_api_key:
        warnings.append("LLM_API_KEY或OPENAI_API_KEY未配置,LLM功能可能无法使用")

    if errors:
        error_msg = "配置错误:\n" + "\n".join(f"  - {e}" for e in errors)
        raise ValueError(error_msg)

    if warnings:
        print("\n⚠️  配置警告:")
        for w in warnings:
            print(f"  - {w}")

    return True


# 打印配置信息(用于调试)
def print_config():
    """打印当前配置(隐藏敏感信息)"""
    print(f"应用名称: {settings.app_name}")
    print(f"版本: {settings.app_version}")
    print(f"服务器: {settings.host}:{settings.port}")
    print(f"高德地图API Key: {'已配置' if settings.amap_api_key else '未配置'}")

    # 检查LLM配置

View on GitHub (pinned to 606a07d341)

Solutions

1. Create backend/.env with a valid AMAP_API_KEY=<your key> from console.amap.com
2. Start the backend from the backend/ directory (or fix the dotenv load path) so .env is actually read
3. Use the exact name AMAP_API_KEY; also add LLM_API_KEY to silence the warning and enable LLM features
4. Run the project's print_config()/validation before deploying to fail fast with readable output

Example fix

# before
# backend/.env missing -> ValueError: 配置错误: - AMAP_API_KEY未配置

# after
# backend/.env
AMAP_API_KEY=your-amap-key
LLM_API_KEY=your-llm-key

import os

def backend_config_ready() -> bool:
    return bool(os.getenv('AMAP_API_KEY'))

if not backend_config_ready():
    raise SystemExit('backend/.env must set AMAP_API_KEY before startup')

try:
    from app.config import validate_config
    validate_config()
except ValueError as e:
    raise SystemExit(f'Fix backend configuration:\n{e}')

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• MX_APIKEY 环境变量未设置，请先设置环境变量： export MX_APIKEY=your_api_key_he
• MX_APIKEY 环境变量未设置，请先设置环境变量： export MX_APIKEY=your_api_key_he
• AI 服务未配置，请设置 OPENAI_API_KEY
• 向量生成器初始化失败: {str(e)}
• Missing required environment variables: {missing_env_vars}.

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