666ghj/MiroFish · error · StarHistoryError

reconstruction must contain only completed UTC dates

Error message

reconstruction must contain only completed UTC dates

What it means

Raised by validate_state() when a daily point's date is >= the generated_at timestamp's date. Reconstruction may only cover fully completed UTC days; the day of generation is still in progress, so any point on or after that day would be a partial count.

Source

Thrown at scripts/star_history.py:419

        _expect_keys(raw_point, {"date", "stars"}, "reconstruction point")
        raw_date = raw_point["date"]
        if not isinstance(raw_date, str):
            raise StarHistoryError("reconstruction date must be a string")
        try:
            point_day = date.fromisoformat(raw_date)
        except ValueError as exc:
            raise StarHistoryError("reconstruction date is invalid") from exc
        if point_day.isoformat() != raw_date:
            raise StarHistoryError("reconstruction date is not canonical")
        stars = _strict_non_negative_int(raw_point["stars"], "reconstruction stars")
        if index == 0 and stars <= 0:
            raise StarHistoryError("first reconstruction point must have stars")
        if previous_day is not None and point_day <= previous_day:
            raise StarHistoryError("reconstruction dates must be strictly increasing")
        if index > 0 and stars <= previous_stars:
            raise StarHistoryError("reconstruction stars must be strictly increasing")
        if point_day >= generated_at.date():
            raise StarHistoryError("reconstruction must contain only completed UTC dates")
        previous_day = point_day
        previous_stars = stars

    snapshots = state["snapshots"]
    if not isinstance(snapshots, list):
        raise StarHistoryError("snapshots must be a list")
    previous_snapshot: datetime | None = None
    first_snapshot: datetime | None = None
    for raw_snapshot in snapshots:
        if not isinstance(raw_snapshot, dict):
            raise StarHistoryError("snapshot must be an object")
        _expect_keys(raw_snapshot, {"at", "stars"}, "snapshot")
        snapshot_at = _parse_state_timestamp(raw_snapshot["at"], "snapshot.at")
        _strict_non_negative_int(raw_snapshot["stars"], "snapshot stars")
        if previous_snapshot is not None and snapshot_at <= previous_snapshot:
            raise StarHistoryError("snapshot timestamps must be strictly increasing")
        if first_snapshot is None:
            first_snapshot = snapshot_at

View on GitHub (pinned to b5b53acc57)

Solutions

1. Remove daily points dated on/after generated_at's UTC date
2. Ensure generated_at is written as the UTC time reconstruction ran, not a future or local time
3. Re-run reconstruction so the in-progress day is naturally excluded

Example fix

// before
"generated_at": "2024-01-02T00:00:00Z",
"daily": [..., {"date": "2024-01-02", "stars": 300}]
// after
"generated_at": "2024-01-02T00:00:00Z",
"daily": [..., {"date": "2024-01-01", "stars": 295}]  // last completed UTC day only

from datetime import datetime, UTC
gen_date = datetime.strptime(
    state["reconstruction"]["generated_at"], "%Y-%m-%dT%H:%M:%SZ"
).replace(tzinfo=UTC).date()
daily = [p for p in daily if p["date"] < gen_date.isoformat()]

def only_completed_dates(daily: list, generated_at: str) -> bool:
    gen = datetime.strptime(generated_at, "%Y-%m-%dT%H:%M:%SZ").date()
    return all(p["date"] < gen.isoformat() for p in daily)

try:
    validate_state(state)
except StarHistoryError as exc:
    if "only completed UTC dates" in str(exc):
        # drop points dated on/after generated_at's UTC date, re-validate
        ...

When it happens

Trigger: validate_state(state) where a daily date equals or exceeds the calendar date of reconstruction.generated_at, e.g. generated_at '2024-01-02T00:00:00Z' with a daily point dated '2024-01-02'.

Common situations: Timezone bugs where generated_at was recorded in local time ahead of UTC; writing today's partial count into daily; backfilling dates incorrectly after downtime.

Related errors

• GitHub star timestamp was not UTC
• clock must return a UTC datetime
• history timezone must be UTC
• first reconstruction point must have stars
• reconstruction stars must be strictly increasing

AI-assisted analysis of 666ghj/MiroFish@b5b53acc57 (2026-08-14). Data as JSON: /api/errors/2aa5795eb9dcae05. Report an issue: GitHub.