datawhalechina/hello-agents · error · ConfigurationError

{name} 必须是数字

Error message

{name} 必须是数字

What it means

Raised by the _read_float helper in src/config.py when an environment variable expected to hold a float (e.g. LLM_TEMPERATURE) is set to a non-numeric value. float(raw_value) raises ValueError, which is chained into ConfigurationError. It fires only when the variable is set and non-empty — unset variables fall back to the default.

Source

Thrown at Co-creation-projects/zenith191-RequirementClarifierAgent/src/config.py:20

from __future__ import annotations

import os
from dataclasses import dataclass


class ConfigurationError(ValueError):
    """配置缺失或配置值无效。"""


def _read_float(name: str, default: float) -> float:
    raw_value = os.getenv(name)
    if raw_value is None or not raw_value.strip():
        return default
    try:
        return float(raw_value)
    except ValueError as exc:
        raise ConfigurationError(f"{name} 必须是数字") from exc


def _read_int(name: str, default: int) -> int:
    raw_value = os.getenv(name)
    if raw_value is None or not raw_value.strip():
        return default
    try:
        return int(raw_value)
    except ValueError as exc:
        raise ConfigurationError(f"{name} 必须是整数") from exc


@dataclass(frozen=True)
class LLMSettings:
    """创建 HelloAgentsLLM 所需的显式配置。"""

    model: str
    api_key: str

View on GitHub (pinned to 606a07d341)

Solutions

1. Check the exact value: print the env var or inspect .env for the float-typed settings (LLM_TEMPERATURE).
2. Fix the value to a plain decimal like 0.2 (dot separator, no quotes or units).
3. Unset the variable if you want the documented default instead of overriding it.

Example fix

# .env before
LLM_TEMPERATURE=high

# .env after
LLM_TEMPERATURE=0.2

import os

def read_float(name: str, default: float) -> float:
    raw = os.getenv(name)
    if raw is None or not raw.strip():
        return default
    try:
        return float(raw)
    except ValueError as e:
        raise ValueError(f"{name}={raw!r} is not a valid float") from e

# fail loudly at startup, not mid-request:
LLM_TEMPERATURE = read_float("LLM_TEMPERATURE", 0.2)

try:
    settings = load_settings()
except ConfigurationError as e:
    print(f"Bad config: {e}")
    sys.exit(2)  # config errors should stop startup, not be retried

When it happens

Trigger: Setting LLM_TEMPERATURE=high, LLM_TEMPERATURE=0,7 (comma decimal), or any string with stray characters/quotes in .env or the shell environment, then loading configuration (from_env or equivalent).

Common situations: Copy-pasting config from a tutorial that uses words instead of numbers; locale confusion (comma vs dot decimal); stray quotes in .env like TEMPERATURE="0.3""; CI injecting a wrong secret value into the wrong variable name.

Related errors

• {name} 必须是整数
• Unsupported latency_mode: {latency_mode}
• Unsupported vision_review_mode: {vision_review_mode}
• Unsupported quality_mode: {quality_mode}
• Unsupported document_ingestion_mode: {mode}

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