How to Fix Loan Balance and Unearned Income Sync Errors

Troubleshooting Guide: Resolving Wrong Loan Balances Caused by Unearned Income Sync Issues (LMS)

Problem Statement

You may encounter a scenario where a customer’s Loan Balance summary card displays an incorrect amount that does not match their actual payment history.

This happens when a customer pays more than the required amount for a specific installment. The system correctly preserves this excess amount for the next installment, labeling it as Unearned Income. However, due to a background synchronization issue, the system may fail to automatically update the main dashboard card, resulting in an inaccurate loan balance.


Step-by-Step Resolution Guide

If a customer has made an overpayment on an installment but their main loan balance card is not updating correctly, follow these steps to manually sync the system:

  1. Open the Customer Profile: Search for the customer and open the specific loan account that is reflecting the incorrect balance.


2. Refresh the Balances: Click on the action dropdown menu on the top right of the loan panel (as shown in the image below). Select Refresh Balances. This commands the system to re-sync the ledger data and recalculate the front-end display.


After completing this action, navigate back to the main customer profile view to verify the balance. If the loan balance card now reflects 0.00, the sync was successful and the process is complete. If it does not update, continue to the next step.

3. Transfer the Unearned Income: If the balance card still fails to update after refreshing, open the action menu again and select Transfer unearned income. This manually pushes the preserved excess payment out of the unearned income reserve and applies it directly to the active loan balance.



By successfully executing the unearned income settlement, the system re-calculates the dashboard data to mirror the true ledger state. As demonstrated in the image below, navigating back to the main customer profile for Wanyama Wangila confirms that the frontend sync error is completely resolved. The Loan Balance card now accurately updates to reflect 0.00 KES, confirming that the manual intervention successfully wiped out the ghost balance and restored alignment across the client's account summary.