HKUDS/Vibe-Trading · error · ValueError

quarter {value!r} is not a calendar quarter end; use 03-31,

Error message

quarter {value!r} is not a calendar quarter end; use 03-31, 06-30, 09-30 or 12-31

What it means

When a YYYY-MM-DD form is supplied, the (month, day) must exactly match one of the calendar quarter ends (03-31, 06-30, 09-30, 12-31). Any other date — even a valid one like 2026-03-30 — is rejected because the API needs true quarter ends.

Source

Thrown at agent/src/tools/institutional_holdings_tool.py:361

    Raises:
        ValueError: When the text is not a recognizable quarter, the year is
            outside ``1993..current+1``, or the date is not a quarter end.
    """
    text = str(value).strip().upper().replace(" ", "")
    match = re.fullmatch(r"(\d{4})-?Q([1-4])", text)
    if match:
        year, quarter = int(match.group(1)), int(match.group(2))
    else:
        match = re.fullmatch(r"(\d{4})-(\d{1,2})-(\d{1,2})", text)
        if not match:
            raise ValueError(
                f"quarter {value!r} is not recognizable; use '2026Q1' or a quarter-end date '2026-03-31'"
            )
        year, month, day = (int(g) for g in match.groups())
        quarter = next((q for q, md in _QUARTER_ENDS.items() if md == (month, day)), None)
        if quarter is None:
            raise ValueError(
                f"quarter {value!r} is not a calendar quarter end; use 03-31, 06-30, 09-30 or 12-31"
            )
    if not _MIN_QUARTER_YEAR <= year <= date.today().year + 1:
        raise ValueError(f"quarter year {year} is outside {_MIN_QUARTER_YEAR}..{date.today().year + 1}")
    month, day = _QUARTER_ENDS[quarter]
    return f"{year:04d}-{month:02d}-{day:02d}"


def _quarter_label(period_end: Optional[str]) -> Optional[str]:
    """Render a ``YYYY-MM-DD`` quarter end as ``YYYYQn``, or ``None`` if unusable."""
    if not period_end or len(str(period_end)) < 7:
        return None
    text = str(period_end)
    try:
        year, month = int(text[:4]), int(text[5:7])
    except ValueError:
        return None
    quarter = next((q for q, md in _QUARTER_ENDS.items() if md[0] == month), None)

View on GitHub (pinned to 80ffdda44c)

Solutions

  1. Use the exact quarter-end dates: 03-31, 06-30, 09-30, 12-31
  2. Prefer the 'YYYYQn' shorthand which avoids date math entirely
  3. Snap dates to quarter ends programmatically before calling

Example fix

# before
execute(quarter="2026-04-01")
# after
execute(quarter="2026Q1")  # or "2026-03-31"
Defensive patterns

Strategy: validation

Validate before calling

from datetime import date
QUARTER_ENDS = {3:(3,31),6:(6,30),9:(9,30),12:(12,31)}
d = date.fromisoformat(q)
assert (d.month, d.day) in QUARTER_ENDS.values(), f"{q} is not a quarter end"

Type guard

def is_calendar_quarter_end(q: str) -> bool:
    from datetime import date
    try:
        d = date.fromisoformat(q)
    except ValueError:
        return False
    return (d.month, d.day) in {(3,31),(6,30),(9,30),(12,31)}

Try / catch

try:
    qn = _parse_quarter(q)
except ValueError as e:
    if "not a calendar quarter end" in str(e):
        qn = _parse_quarter(f"{d.year}Q{(d.month-1)//3+1}")
    else:
        raise

Prevention

When it happens

Trigger: quarter='2026-04-01', '2026-03-30', or a fiscal quarter end that is not a calendar quarter end.

Common situations: Companies with non-calendar fiscal years; users rounding the quarter boundary; timezone/off-by-one date math.

Related errors

AI-assisted analysis of HKUDS/Vibe-Trading@80ffdda44c (2026-08-28). Data as JSON: /api/errors/109fa5bcffab9cdd. Report an issue: GitHub.