HKUDS/Vibe-Trading · error · ValueError

cash flow on {when} lies outside the valuation window {first

Error message

cash flow on {when} lies outside the valuation window {first}..{last}; extend the valuations or trim the flows rather than dropping the flow

What it means

_assign_flows_to_periods buckets each external cash flow into a sub-period of the valuation schedule; a flow dated before the first valuation or after the last cannot be assigned to any period. The library raises rather than silently dropping the flow, because dropping client money would misstate the return.

Source

Thrown at agent/src/quantlib/performance.py:482

    *last* valuation falls outside the window.

    Args:
        dates: Valuation dates in ascending order.
        flows: Portfolio-perspective ``(date, amount)`` pairs.
        flow_timing: One of :data:`FLOW_TIMING_END` / :data:`FLOW_TIMING_START`.

    Returns:
        One net flow per interval, so ``len(dates) - 1`` entries.

    Raises:
        ValueError: If a flow falls outside the valuation window. Dropping it
            silently would move the client's money into the manager's return.
    """
    first, last = dates[0], dates[-1]
    buckets = [0.0] * (len(dates) - 1)
    for when, amount in flows:
        if when < first or when > last:
            raise ValueError(
                f"cash flow on {when} lies outside the valuation window "
                f"{first}..{last}; extend the valuations or trim the flows "
                "rather than dropping the flow"
            )
        if flow_timing == FLOW_TIMING_END:
            if when == first:
                raise ValueError(
                    f"cash flow on {when} coincides with the opening valuation "
                    f"and flow_timing={FLOW_TIMING_END!r} places it inside the "
                    "opening value, where it would be counted twice. Use "
                    f"flow_timing={FLOW_TIMING_START!r}, or start the "
                    "valuations one period earlier."
                )
            # First interval whose closing date is at or after the flow.
            index = next(k for k in range(1, len(dates)) if dates[k] >= when) - 1
        else:
            if when == last:
                raise ValueError(

View on GitHub (pinned to 80ffdda44c)

Solutions

1. Extend the valuations list to cover the earliest flow and latest flow dates.
2. Filter flows to the window [first_valuation_date, last_valuation_date] if the out-of-window flows belong to a different reporting period.
3. Fix date parsing/timezone bugs that push a flow outside the window by one day.

Example fix

# before
time_weighted_return(
    valuations=[(date(2024,1,31), 100_000.0), (date(2024,3,31), 110_000.0)],
    flows=[CashFlow(date=date(2024,1,15), amount=5_000.0, kind='contribution')],  # before window
)

# after
time_weighted_return(
    valuations=[(date(2024,1,15), 95_000.0), (date(2024,1,31), 100_000.0), (date(2024,3,31), 110_000.0)],
    flows=[CashFlow(date=date(2024,1,15), amount=5_000.0, kind='contribution')],
)

lo, hi = marks[0][0], marks[-1][0]
assert all(lo <= f.date <= hi for f in external_flows(flows)), 'flow outside valuation window'

try:
    twr = time_weighted_return(marks, flows)
except ValueError as e:
    if 'outside the valuation window' in str(e):
        lo, hi = marks[0][0], marks[-1][0]
        twr = time_weighted_return(marks, [f for f in flows if lo <= f.date <= hi])
    else:
        raise

When it happens

Trigger: Calling time_weighted_return with a flow dated before dates[0] or after dates[-1] of the valuation list, e.g. valuations starting 2024-01-31 but a contribution on 2024-01-15.

Common situations: Valuation window chosen as a fiscal period while the flows feed covers a longer range; off-by-one at month end; timezone/date parsing shifting a flow one day past the last mark.

Related errors

• a kind cannot be both external and internal; overlapping: {'
• cash-flow kind {flow.kind!r} on {flow.date} is classified ne
• cash flow on {when} coincides with the opening valuation and
• brinson_fachler needs at least one sector
• portfolio and benchmark weights must sum to the same total f

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