sansan0/TrendRadar · error · ValueError

timeline 缺少必须字段: {key}

Error message

timeline 缺少必须字段: {key}

What it means

Raised by the scheduler's startup timeline validator when a required top-level key is missing from the timeline dict. The contract requires four keys: default, periods, day_plans, week_map. This fails fast at startup (or whenever _validate_timeline is called) rather than at resolution time, naming the first missing key.

Source

Thrown at trendradar/core/scheduler.py:323

            date_str: 日期 YYYY-MM-DD
        """
        self.storage.record_period_execution(date_str, period_key, action)

    # ========================================
    # 校验
    # ========================================

    def _validate_timeline(self, timeline: Dict[str, Any]) -> None:
        """
        启动时校验 timeline 配置

        Raises:
            ValueError: 配置不合法时抛出
        """
        required_top_keys = ["default", "periods", "day_plans", "week_map"]
        for key in required_top_keys:
            if key not in timeline:
                raise ValueError(f"timeline 缺少必须字段: {key}")

        # week_map 必须覆盖 1..7
        for day in range(1, 8):
            if day not in timeline["week_map"]:
                raise ValueError(f"week_map 缺少星期映射: {day}")

        # day_plan 引用完整性
        for day, plan_key in timeline["week_map"].items():
            if plan_key not in timeline["day_plans"]:
                raise ValueError(
                    f"week_map[{day}] 引用了不存在的 day_plan: {plan_key}"
                )

        # period 引用完整性
        for plan_key, plan in timeline["day_plans"].items():
            for period_key in plan.get("periods", []):
                if period_key not in timeline["periods"]:
                    raise ValueError(

View on GitHub (pinned to 8ee26026ba)

Solutions

1. Add the missing top-level key named in the message (empty dict is acceptable for periods/day_plans in most setups).
2. Copy the full skeleton from the shipped example timeline and fill it in.
3. Check YAML indentation — a section nested one level too deep becomes 'missing' at the top level.
4. Validate timelines in tests by calling _validate_timeline directly.

Example fix

# before
custom:
  default: {...}
  day_plans: {...}
  week_map: {...}
# after (add periods)
custom:
  default: {...}
  periods: {}
  day_plans: {...}
  week_map: {...}

REQUIRED = ["default", "periods", "day_plans", "week_map"]
missing = [k for k in REQUIRED if k not in timeline]
if missing:
    raise ValueError(f"timeline missing keys: {missing}")
scheduler = Scheduler(schedule_config, timeline_data)  # now safe

def timeline_has_required_keys(t: dict) -> bool:
    return all(k in t for k in ("default", "periods", "day_plans", "week_map"))

try:
    scheduler = Scheduler(schedule_config, timeline_data)
except ValueError as e:
    if "timeline 缺少必须字段" in str(e):
        raise SystemExit(f"timeline config incomplete: {e}")
    raise

When it happens

Trigger: A custom timeline (preset: custom) that defines day_plans and week_map but omits 'default' or 'periods'; YAML indentation placing a section under the wrong parent; a programmatically built timeline missing a section.

Common situations: Starting from a minimal example timeline that skips optional-looking sections; upgrading configs where a key was renamed; typos in top-level key names ('defaults' vs 'default').

Related errors

• 不支持的传输模式: {transport}
• DATA_NOT_FOUND
• 未知的预设模板: '{preset}'，可选值: {', '.join(presets.keys())}, custom
• week_map 缺少星期映射: {day}
• week_map[{day}] 引用了不存在的 day_plan: {plan_key}

AI-assisted analysis of sansan0/TrendRadar@8ee26026ba (2026-08-15). Data as JSON: /api/errors/597b03893e0d1013. Report an issue: GitHub.