> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lead.bank/llms.txt
> Use this file to discover all available pages before exploring further.

# Balances & Transactions Files Troubleshooting

> Symptom-first guide to the most common Balance and Transaction file rejections — reconciliation breaks, missing balances, type-specific amount rules, and cadence failures — and how to fix and resubmit.

When a Balance or Transaction file fails validation, the 🔴 [Slack alert](/file-reference/delivery/slack-alerts) names the error code, the failing detail, and the action to take. This page covers the most common failures symptom-first; the complete catalog is [File Submission Validation Errors](/file-reference/delivery/errors).

**The universal recovery loop:** fix the flagged records, upload a new version of the corrected file (same batch), and Lead re-validates the latest version of each file in the batch. Resubmit before the next cycle where possible so one bad day doesn't cascade into the next day's T−1 checks.

<Note>
  **Error code renames effective August 4, 2026.** Several balance-related codes dropped the legacy `account_balance` term (e.g., `transaction_missing_account_balance` → `transaction_missing_balance`; `balance_cannot_be_closed_with_processing_funding` → `balance_cannot_be_terminal_with_processing_funding`). If your automation keys off code strings, use the new codes — the [changelog entry](/changelog) has the full mapping.
</Note>

<AccordionGroup>
  <Accordion title="Balance mismatch: reported balance doesn't equal its components or yesterday-plus-activity" icon="warning">
    **Symptom:** errors like `unexpected_balance`, `unexpected_past_due_balance`, `unexpected_dispute_balance`, or `unexpected_charge_off_balance`. The alert detail shows the expected sum, your submitted value, the delta, and the Sample ID of a failing record — e.g., *`balance` (316125.78) was expected to be 316124.78 (delta: 1.00), the sum of `outstanding_principal`, `outstanding_interest`, and `outstanding_fee`.*

    **Likely causes:** a component field out of sync with the total (rounding, a fee booked to the wrong bucket); or the day's transactions don't account for the balance movement, breaking the invariant **balance(T) = balance(T−1) + T's transactions**.

    **How to confirm:** pull the Sample ID's record from your file, recompute the named components, then recompute the invariant against yesterday's submitted balance and today's transactions for that `balance_id`.

    **Fix:** correct the component or add the missing transaction, resubmit the file version. Prevention: assert both identities in your pipeline before submission ([Balance Reconciliation](/products/balances-and-transactions/balance-reconciliation)).
  </Accordion>

  <Accordion title="Transaction references a balance that doesn't exist" icon="warning">
    **Symptom:** `transaction_missing_balance` / `transaction_missing_card_balance` (pre-Aug-4: `…_account_balance`), or — for card programs — `previous_active_card_balance_missing`.

    **Likely causes:** the transaction's `balance_id` was never established in a Balance file (or, for credit, never created via the Subledger Balance API); files arrived out of order so the transaction landed before its balance; or a card balance active yesterday is absent from today's file.

    **How to confirm:** search your Balance submissions for the `balance_id`; check whether today's Balance file includes every balance that was active on T−1.

    **Fix:** establish or re-include the balance, then resubmit the transaction file. Balances don't disappear when quiet — an active balance is reported every day until you transition it per [Balance Statuses](/products/balances-and-transactions/balance-statuses).
  </Accordion>

  <Accordion title="Balance references an account that doesn't validate" icon="warning">
    **Symptom:** account-linkage validation failure on new Balance creation.

    **Cause:** every Balance must reference a valid parent [Account](/products/accounts/overview); enforcement begins **October 6, 2026** ([Upcoming Changes](/upcoming-changes#account-validation-during-new-balance-creation)).

    **How to confirm:** `GET /v0/accounts/{id}` for the referenced `account_id` — it must exist and its capabilities must permit the balance type (`deposit` capability for deposit balances; a credit capability for credit balances).

    **Fix:** create the account first (Entity → \[Application →] Account), or correct the `account_id` in your file generation, before the balance is submitted. Review your workflows ahead of October 6.
  </Accordion>

  <Accordion title="Transaction type and amounts disagree" icon="warning">
    **Symptom:** `transaction_activity_check` / `transaction_type_invalid_activity_check`.

    **Cause:** each transaction `type` constrains which amount fields may be non-zero: **`disbursement`** — `principal_amount` > 0; `interest_amount` and `fee_amount` = 0 · **`interest_accrued`** — `interest_amount` > 0; others = 0 · **`fee`** — `fee_amount` > 0; others = 0.

    **Fix:** split composite entries into one transaction per type rather than packing principal, interest, and fees into one record. Valid type/action/transfer-type combinations: [Transaction Types](/products/balances-and-transactions/transaction-types).
  </Accordion>

  <Accordion title="Disbursement fee doesn't match the Funding" icon="warning">
    **Symptom:** `funding_fee_amount_mismatch` on a disbursement transaction.

    **Cause:** when a transaction has `type: disbursement`, `transfer_type: internal_transfer`, and a populated `funding_id`, its `fee_amount` must equal `other_fees.borrower_origination_fee_amount` on that Funding.

    **How to confirm:** `GET /v0/fundings/{funding_id}` and compare.

    **Fix:** correct whichever side is wrong — usually the file; the Funding's fee was fixed at creation ([The Funding Object](/products/lending/funding-object)).
  </Accordion>

  <Accordion title="Balance closed while a Funding is still processing" icon="warning">
    **Symptom:** `balance_cannot_be_terminal_with_processing_funding`.

    **Cause:** you reported a balance into a terminal status (`closed`, or `receivable_transferred`) while a Funding against it is still `processing`.

    **Fix:** wait for the Funding to reach `posted` or `rejected` (the `funding.posted` webhook, or [Simulate Advance Funding](/api-reference/endpoint/funding/advance-a-funding) in sandbox), then report the terminal status.
  </Accordion>

  <Accordion title="No alert at all / file seemingly ignored" icon="warning">
    **Symptom:** no 🟢 or 🔴 for a submission.

    **Likely causes:** file delivered after the **6:00 a.m. CT** cutoff, so it missed the day's cycle; wrong SFTP path (alerts now include the full file path — check it matches the expected folder); or a filename outside the convention (epoch-timestamp generation time or `v1`/`v2` version suffix — [SFTP setup](/file-reference/sftp-setup)).

    **Fix:** correct path/naming and resubmit; if the cutoff was missed, coordinate with your Lead team on whether the file can join today's cycle or must roll. Remember empty days still require an empty file.
  </Accordion>
</AccordionGroup>

Still stuck? Escalate in your Slack channel with the full file path from the alert, the error code, and the Sample ID — that trio lets Lead locate the exact record immediately.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.