HKUDS/Vibe-Trading · error · BalanceSheetError

BalanceSheetError(balance_sheet.period, assets…

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.

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
Defensive patterns

Strategy: validation

Validate before calling

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)

Type guard

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)

Try / catch

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

Prevention

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

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

Appendix: 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)