datawhalechina/hello-agents · error · ConfigurationError

{name} 必须是整数

Error message

{name} 必须是整数

What it means

Raised by _read_int in src/config.py when an integer-typed env var (e.g. LLM_TIMEOUT) fails int(raw_value). Note int('120.0') also fails — Python's int() rejects decimal strings, unlike float('120'). The original ValueError is chained via 'from exc', preserving the root cause.

Source

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

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
    base_url: str
    temperature: float = 0.2
    timeout: int = 120

    @classmethod
    def from_env(cls) -> "LLMSettings":
        """从 HelloAgents 官方环境变量读取配置并完成校验。"""

        settings = cls(
            model=os.getenv("LLM_MODEL_ID", "").strip(),

View on GitHub (pinned to 606a07d341)

Solutions

1. Set the variable to a bare integer string, e.g. LLM_TIMEOUT=120 (no decimals, no units).
2. If a fractional value was intended, round it to an integer first: LLM_TIMEOUT=120 not 120.0.
3. Verify with: python -c "import os; print(repr(os.getenv('LLM_TIMEOUT')))".

Example fix

# .env before
LLM_TIMEOUT=120.0

# .env after
LLM_TIMEOUT=120

import os

def read_int(name: str, default: int) -> int:
    raw = os.getenv(name)
    if raw is None or not raw.strip():
        return default
    return int(float(raw))  # accept '120.0' gracefully, or:
    # return int(raw)  # strict: rejects decimals — pick one policy and document it

try:
    settings = load_settings()
except ConfigurationError as e:
    if "整数" in str(e):
        print("Integer env var malformed — check LLM_TIMEOUT")
    raise

When it happens

Trigger: Setting LLM_TIMEOUT=120s, LLM_TIMEOUT=120.0, or LLM_TIMEOUT=-1 in .env, then constructing settings from the environment.

Common situations: Adding a unit suffix ('30s') copied from a docker-compose example; entering 120.5 because the field was assumed to accept floats; whitespace-embedded values from CI secrets.

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/75a7dc41ac16192b. Report an issue: GitHub.