datawhalechina/hello-agents · error · ValueError

配置缺少必需的键: {missing_keys}

Error message

配置缺少必需的键: {missing_keys}

What it means

ValueError from utils.helpers.validate_config when one or more required keys are absent from the config dict; the missing key names are included in the message. It is a fail-fast startup check used to reject incomplete configuration before downstream code dereferences the keys.

Source

Thrown at Co-creation-projects/YYHDBL-HelloCodeAgentCli/utils/helpers.py:36

    """
    if timestamp is None:
        timestamp = datetime.now()
    return timestamp.strftime(format_str)

def validate_config(config: Dict[str, Any], required_keys: list) -> bool:
    """
    验证配置是否包含必需的键
    
    Args:
        config: 配置字典
        required_keys: 必需的键列表
        
    Returns:
        是否验证通过
    """
    missing_keys = [key for key in required_keys if key not in config]
    if missing_keys:
        raise ValueError(f"配置缺少必需的键: {missing_keys}")
    return True

def safe_import(module_name: str, class_name: Optional[str] = None) -> Any:
    """
    安全导入模块或类
    
    Args:
        module_name: 模块名
        class_name: 类名（可选）
        
    Returns:
        导入的模块或类
    """
    try:
        module = importlib.import_module(module_name)
        if class_name:
            return getattr(module, class_name)
        return module

View on GitHub (pinned to 606a07d341)

Solutions

1. Add the listed missing keys to the config dict/file with valid values.
2. Check spelling and nesting — flatten or access nested values before validating.
3. Log the full expected key list next to the error during onboarding so users know the schema.

Example fix

# before
validate_config(cfg, ['api_key', 'base_url'])
# cfg = {'apiKey': '...'}  -> ValueError: missing ['api_key', 'base_url']

# after
cfg = {'api_key': '...', 'base_url': 'https://...'}
validate_config(cfg, ['api_key', 'base_url'])

def config_has_keys(config: dict, required: list) -> bool:
    return all(k in config for k in required)

if not config_has_keys(cfg, REQUIRED_KEYS):
    missing = [k for k in REQUIRED_KEYS if k not in cfg]
    raise ValueError(f'fill in config keys: {missing}')

def is_complete_config(config: dict, required: list) -> bool:
    return isinstance(config, dict) and all(k in config and config[k] is not None for k in required)

try:
    validate_config(config, REQUIRED_KEYS)
except ValueError as e:
    raise SystemExit(f'startup aborted — fix config: {e}')

When it happens

Trigger: Calling validate_config(config, ['api_key', 'base_url']) with a dict missing either key; keys present but under different names/casing ('apiKey' vs 'api_key'); config loaded from a JSON/YAML file that omitted sections.

Common situations: Config schema evolves and older files lack new keys; nested keys expected flat (config['llm']['api_key'] vs config['api_key']); environment-dependent configs where one env's file is incomplete.

Related errors

• 请在 .env 中配置 LLM_MODEL_ID, LLM_API_KEY, LLM_BASE_URL
• API密钥和服务地址必须被提供或在.env文件中定义。
• 无效的 JSON 格式: {str(e)}
• 配置必须是 JSON 对象
• 缺少必需字段: llm

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