{"record":{"id":"35bf69c2ebb02486","repo":"HKUDS/Vibe-Trading","slug":"balancesheeterror-balance-sheet-period-assets-li","errorCode":null,"errorMessage":"BalanceSheetError(balance_sheet.period, assets, liabilities, equity, tolerance)","messagePattern":"BalanceSheetError\\(balance_sheet\\.period, assets, liabilities, equity, tolerance\\)","errorType":"validation","errorClass":"BalanceSheetError","httpStatus":null,"severity":"error","filePath":"agent/src/quantlib/valuation/threestatement.py","lineNumber":447,"sourceCode":"\n    Args:\n        balance_sheet: The balance sheet to check.\n        tolerance: Largest tolerated ``|residual| / max(total_assets, 1.0)``.\n            Defaults to :data:`BALANCE_TOLERANCE_REL`.\n\n    Raises:\n        BalanceSheetError: If ``assets != liabilities + equity`` beyond\n            ``tolerance``, or if any of ``assets``, ``liabilities`` or\n            ``equity`` is not a finite number. The exception carries the\n            exact residual.\n    \"\"\"\n    assets = balance_sheet.total_assets\n    liabilities = balance_sheet.total_liabilities\n    equity = balance_sheet.total_equity\n    residual = assets - liabilities - equity\n    scale = max(abs(assets), 1.0)\n    if not math.isfinite(residual) or abs(residual) > tolerance * scale:\n        raise BalanceSheetError(balance_sheet.period, assets, liabilities, equity, tolerance)\n\n\ndef _require_finite(value: float, name: str, model: str) -> float:\n    \"\"\"Check a value is a finite number, refusing NaN and infinity.\n\n    Args:\n        value: The candidate value.\n        name: Field name for the error message.\n        model: Model name for the error message.\n\n    Returns:\n        ``value`` as a float.\n\n    Raises:\n        ValuationError: If the value is not a finite number. A non-finite\n            driver or opening figure would otherwise flow into the projection\n            and surface as a misleading \"did not converge\" error.\n    \"\"\"","sourceCodeStart":429,"sourceCodeEnd":465,"githubUrl":"https://github.com/HKUDS/Vibe-Trading/blob/80ffdda44c5c4db0dd84d70e051cca591cea67df/agent/src/quantlib/valuation/threestatement.py#L429-L465","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the BalanceError fields (period, assets, liabilities, equity) and fix the underlying figure that breaks the identity.","If the imbalance is just rounding, raise balance_tolerance (it is relative to assets scale).","Scrub inputs for NaN/inf and unit-scale errors before constructing BalanceSheet objects."],"exampleFix":"# before\nbs = BalanceSheet(period=\"FY24\", total_assets=1_000, total_liabilities=600, total_equity=500)\ncheck_balance_sheet(bs)  # residual 100 - not 500\n# after\nbs = BalanceSheet(period=\"FY24\", total_assets=1_100, total_liabilities=600, total_equity=500)\ncheck_balance_sheet(bs)  # balanced within tolerance","handlingStrategy":"validation","validationCode":"resid = bs.total_assets - bs.total_liabilities - bs.total_equity\nimport math\nassert math.isfinite(resid) and abs(resid) <= tol * max(abs(bs.total_assets), 1.0)","typeGuard":"def is_balanced(bs, tol: float = 1e-6) -> bool:\n    import math\n    r = bs.total_assets - bs.total_liabilities - bs.total_equity\n    return math.isfinite(r) and abs(r) <= tol * max(abs(bs.total_assets), 1.0)","tryCatchPattern":"from quantlib.valuation.threestatement import BalanceSheetError\ntry:\n    check_balance_sheet(bs)\nexcept BalanceSheetError as e:\n    logger.warning('imbalance at %s: %s', e.period, e)","preventionTips":["Always run check_balance_sheet on constructed sheets before projections","Choose tolerance relative to the reporting currency's rounding granularity","Reject NaN rows at ingestion time"],"tags":["valuation","three-statement","accounting-identity","balance-sheet"],"backgroundTag":"balance-sheet-unbalanced","analyzedSha":"80ffdda44c5c4db0dd84d70e051cca591cea67df","analyzedAt":"2026-08-28T12:46:38.989Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}