Interest recalculation in Fineract: why your loan schedule changed overnight

A loan officer opens an account they have not touched in a week and the repayment schedule is different. Same loan, same borrower, but the installments have moved. Nobody posted a transaction. Nobody edited anything. The natural conclusion is that something is broken.

Almost always, nothing is. What you are looking at is interest recalculation, and it is one of the most useful and most misunderstood features in Fineract. It is also, once in a while, really buggy. The hard part is telling those two apart, so that is what this post is for: what recalculation does, what makes a schedule move, and how to decide whether you are looking at the engine working exactly as configured or a real defect.

We run managed Fineract, so we field this exact question. Here is how to read it.

First: are you even looking at the same schedule?

Before anything else, this. A loan with recalculation enabled has two schedules, and Fineract shows you both. The Original Schedule is frozen at disbursement and never changes. The Repayment Schedule is the live one, and it gets rewritten as the loan deviates from plan. Most "the schedule changed" reports are someone comparing the live Repayment schedule against their memory of the original.

So step one is never theoretical. Open the loan, look at the Original Schedule tab, and compare it to the current Repayment Schedule. If they differ, the schedule did change, and now the question is why. If your team only ever looks at one tab, half of these mysteries evaporate on the spot.

What recalculation is, and whether it is even on

Interest recalculation re-derives the interest on a loan from the actual outstanding principal and the actual dates money moved, rather than from the fixed plan drawn up at disbursement. Pay early and your principal drops faster than planned, so less interest accrues and future installments shrink. Pay late and the principal sits there longer, so more interest accrues and they grow. The schedule is no longer a contract carved in stone; it is a live projection.

Two things about it surprise people.

It is off by default. Recalculation is a per-product setting, isInterestRecalculationEnabled, and it only works on declining-balance loans. If a product does not have it switched on, the schedule should not move on its own, and a schedule that does move on such a product is a much stronger bug signal.

And the settings are frozen at disbursement. This is the one that bites hardest. When a loan is disbursed, it captures the product's recalculation configuration as it stood that day. Editing the product later does not reach back and change loans already on the books. So if you discover a product was misconfigured, the loans already disbursed under it keep the old behaviour, and correcting them is a database job, not a settings change. Get the configuration right before you disburse, because afterwards is expensive.

What actually makes a schedule move

When recalculation is on, any payment that deviates from the plan triggers a rewrite: paying early or over, paying late, paying less than was due, or prepaying, as does a back-dated entry. Under the hood the rule is broader still, because the engine recomputes whenever a transaction posts against the loan or a repayment simply falls due.

One behaviour inside that list catches almost everyone. When recalculation is on, any amount a borrower pays beyond what is currently due goes straight onto the outstanding principal, and it does this regardless of the repayment strategy you configured for ordinary payments. People set up a transaction processing order with care, watch an overpayment skip all of it and land on principal, and assume something went wrong. It did not. Excess plus recalculation means principal reduction, by design.

Then there is the part that produces the literal "overnight" symptom. Recalculation does not only fire the instant a payment lands. There is a job that runs at close of business every day, the same close-of-business cycle that ages your loans and posts accruals, and one of its steps walks every active loan with recalculation enabled and rewrites the schedule wherever the calculated interest no longer matches. For an overdue loan this is relentless: every night it adds another day of interest on the outstanding principal to the final installment. The loan is not being touched by anyone. The schedule grows anyway, a little more each night, because that is what daily interest on an unpaid balance does. That is your overnight change, and it is the system telling the truth about a loan that is behind.

The settings that decide how it moves

If recalculation is the engine, these are the dials. You do not need to memorise them, but you need to know they exist, because two products with recalculation "on" can behave completely differently depending on how they are set.

• Compounding. What happens to interest or fees that go unpaid: do they get folded into the principal base for the next period, or not? The options are none, interest, fee, or interest and fee. "None" keeps overdue interest from itself earning interest; the others let it compound. This alone changes how fast an overdue balance grows.
• Rest frequency. How often the engine recomputes interest against the real outstanding balance: same as the repayment period, daily, weekly, or monthly. A daily rest rewards on-time and early payers with less interest and penalises overdue ones with more, because it is constantly re-reading the actual balance. A coarser rest smooths that out.
• Advance-payment strategy. When a borrower pays ahead, what gives: each future installment shrinks (reduce the EMI), the loan ends sooner (reduce the number of installments), or the surplus is parked against the next repayments. Same overpayment, three completely different-looking schedules depending on this one choice.
• Pre-closure strategy. When someone settles early, whether interest is charged up to the actual pay-off date or up to the next rest date.

Most "why does it look like that" questions resolve to one of these four being set differently from what the person expected. They are not bugs. They are the knobs.

Config, or a real bug?

Here is the honest part, because recalculation is not flawless and pretending it is would not help you.

Plenty of reported "bugs" here are the engine behaving correctly. A schedule that keeps changing after the maturity date on an overdue loan has been reported and closed as not-a-problem more than once. So has daily interest "ignoring" the days-in-month convention, which is intentional. The overpayment-hits-principal behaviour gets filed as a bug regularly and closed every time. Before you escalate, run the checklist:

1. Did it actually change? Compare Original against Repayment.
2. Is recalculation even enabled on this product? If not, be suspicious.
3. Did a payment deviate from plan, or a back-dated entry post, or is this just an overdue loan the nightly job is aging? Find the cause before judging the effect.
4. Does the size of the change roughly fit the deviation? A payment a few days early nudging the next installment is normal. A one-cent overpayment that re-levels every remaining installment is not.
5. Check your version and your loan type.

That last point is the one that matters most, because the genuine bugs cluster. The newer progressive-loan engine had a real run of recalculation defects across the 1.12 to 1.14 releases: wrong installments when the rest frequency was set to same-as-repayment, interest vanishing from future installments after certain payments, pay-off amounts coming out short. Most of those are fixed now, which is exactly why your version matters. The older cumulative engine is comparatively stable. And there are still a couple of open ones worth knowing: a cumulative, floating-rate loan where a one-cent overpayment triggers a full recalculation but an exact payment does not, and a rate change that quietly ignores the reduce-EMI setting; and a charge-off that produces a broken schedule. Both are narrow and reproducible, which is what a real bug looks like, as opposed to "the number moved and I do not know why."

So the rule of thumb: if the change tracks a real deviation, the magnitude is sane, and you are on a current version with a cumulative loan, it is configuration doing its job. If a trivial or zero deviation caused a large change, or the numbers simply do not reconcile, and especially if you are on a progressive or floating-rate product, you may have found something real. Capture the loan, the exact transactions, both schedules, and the version before you report it.

So, what should you do?

Decide whether you want recalculation at all, per product, before you disburse a single loan, because you cannot cleanly change your mind later. If you do want it, set the compounding, rest frequency, and advance-payment strategy deliberately, and write down what you chose, so that six months from now nobody mistakes the result for a malfunction. Train whoever reads schedules to compare the Original and Repayment tabs first. And keep your version current, because this is one of the areas where staying close to upstream really does buy you fewer surprises. The sibling decision, whether to run these as progressive or cumulative loans in the first place, shapes how much of this you will ever touch.

That is the work we take off your plate. Finecko runs managed Apache Fineract with the products configured deliberately, the recalculation settings chosen on purpose and documented, and the version kept current so the recalculation fixes land before your loan officers file a ticket. If you would rather run it yourself, the map above is the one the docs never quite draw in one place: a schedule that changes by itself is usually the engine being honest about a loan that deviated, and the trick is knowing the difference between honest and wrong.