HKUDS/Vibe-Trading · error · BalanceSheetError

BalanceSheetError(balance_sheet.period, assets, liabilities,

Error message

BalanceSheetError(balance_sheet.period, assets, liabilities, equity, tolerance)

What it means

check_balance_sheet asserts the accounting identity assets = liabilities + equity within a relative tolerance (tolerance * max(|assets|, 1.0)). If the residual is non-finite or exceeds that scaled tolerance it raises BalanceSheetError carrying the period and the offending figures. This catches corrupted or hand-built balance sheets before they seed a three-statement projection.

Source

Thrown at agent/src/quantlib/valuation/threestatement.py:447

    Args:
        balance_sheet: The balance sheet to check.
        tolerance: Largest tolerated ``|residual| / max(total_assets, 1.0)``.
            Defaults to :data:`BALANCE_TOLERANCE_REL`.

    Raises:
        BalanceSheetError: If ``assets != liabilities + equity`` beyond
            ``tolerance``, or if any of ``assets``, ``liabilities`` or
            ``equity`` is not a finite number. The exception carries the
            exact residual.
    """
    assets = balance_sheet.total_assets
    liabilities = balance_sheet.total_liabilities
    equity = balance_sheet.total_equity
    residual = assets - liabilities - equity
    scale = max(abs(assets), 1.0)
    if not math.isfinite(residual) or abs(residual) > tolerance * scale:
        raise BalanceSheetError(balance_sheet.period, assets, liabilities, equity, tolerance)


def _require_finite(value: float, name: str, model: str) -> float:
    """Check a value is a finite number, refusing NaN and infinity.

    Args:
        value: The candidate value.
        name: Field name for the error message.
        model: Model name for the error message.

    Returns:
        ``value`` as a float.

    Raises:
        ValuationError: If the value is not a finite number. A non-finite
            driver or opening figure would otherwise flow into the projection
            and surface as a misleading "did not converge" error.
    """

View on GitHub (pinned to 80ffdda44c)

Solutions

1. Inspect the BalanceError fields (period, assets, liabilities, equity) and fix the underlying figure that breaks the identity.
2. If the imbalance is just rounding, raise balance_tolerance (it is relative to assets scale).
3. Scrub inputs for NaN/inf and unit-scale errors before constructing BalanceSheet objects.

Example fix

# before
bs = BalanceSheet(period="FY24", total_assets=1_000, total_liabilities=600, total_equity=500)
check_balance_sheet(bs)  # residual 100 - not 500
# after
bs = BalanceSheet(period="FY24", total_assets=1_100, total_liabilities=600, total_equity=500)
check_balance_sheet(bs)  # balanced within tolerance

resid = bs.total_assets - bs.total_liabilities - bs.total_equity
import math
assert math.isfinite(resid) and abs(resid) <= tol * max(abs(bs.total_assets), 1.0)

def is_balanced(bs, tol: float = 1e-6) -> bool:
    import math
    r = bs.total_assets - bs.total_liabilities - bs.total_equity
    return math.isfinite(r) and abs(r) <= tol * max(abs(bs.total_assets), 1.0)

from quantlib.valuation.threestatement import BalanceSheetError
try:
    check_balance_sheet(bs)
except BalanceSheetError as e:
    logger.warning('imbalance at %s: %s', e.period, e)

When it happens

Trigger: Passing an opening or projected BalanceSheet where total_assets - total_liabilities - total_equity is NaN/inf or larger than tolerance*scale — e.g. retained-earnings plug computed wrong, or assets left at 0 while liabilities carry values.

Common situations: Building opening balance sheets from messy ERP/CSV extracts; unit mismatches (thousands vs millions); NaNs introduced by upstream merges; tolerance set too tight for rounded reported figures.

Related errors

• {model}: {name} must be a number, got {value!r}
• {model}: {name} must be a finite number, got {numeric!r}
• {MODEL_NAME}: every driver sequence must share one length (o
• {MODEL_NAME}: driver sequences are empty; at least one proje
• ConvergenceError(period, iterations, delta, circularity_tole

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