ERPNext version 15 to 16 upgrade

The first step is an inventory, and it should be complete before anyone runs a migration. List every custom Frappe app with its pinned dependencies, then every Server Script, Client Script, custom field, print format and scheduled job in the production site. Record where each item lives, which DocTypes it reads or writes, and who owns it. Then sort the list by exposure. Items that override or extend core DocTypes such as Sales Invoice, Journal Entry, Payment Entry or Stock Entry come first. Items that post to the general ledger or change stock valuation come next, followed by anything that exchanges data with an external system such as a bank feed, payment gateway, e-commerce store or payroll provider. Print formats and cosmetic client logic usually sit at the bottom. This ordering tells the team where the staging effort should concentrate.

Each item then needs two checks. The first is a read of the v16 release notes against the specific DocTypes, controller methods, hooks and APIs that the item touches. Do not assume a change is irrelevant because the feature sounds unrelated, and do not assume it applies without reading the note. Record the result for each item as affected, unaffected or unclear. The second check is a run in staging. Restore a recent copy of production, install the same custom apps at the versions the team intends to ship, run bench migrate, and exercise each document event, button, report and scheduled job against realistic records. A check passes only when the output matches the expected accounting and stock results, not when the page merely loads. Keep a simple register of item, check method, result and owner.

Custom Server Scripts need their own review. Since version 15, Server Scripts are disabled by default and run only when the server_script_enabled setting allows it. Confirm that the setting is enabled in staging and in production before cutover, and verify that each document event actually fires after the move. A disabled script does not always produce a visible error, so a missing validation or posting side effect may only surface later in a reconciliation. The move also changes where logic can live. Frappe Cloud public shared benches do not allow Server Scripts, so any script that must keep running on that tier has to move into a custom app, or the team has to choose a hosting option that permits Server Scripts. Ask the hosting provider to confirm the current plan terms in writing.

Plan for two outcomes. Items the team should expect to rewrite include overrides of core controllers, scripts that depend on internal methods that the release notes mark as changed, code that posts to accounting or stock, integration code that calls APIs whose behavior changed, and any Server Script that must run on a Frappe Cloud public shared bench. Items that can usually be retested only include print formats, custom fields with no logic attached, Client Scripts that only set field values or toggle visibility, reports that read standard tables without changing them, and scheduled jobs that call stable public methods. Even retest-only items should pass the staging run, because a dependency update can change behavior without any code change. Label each item with the expected outcome before work starts, so the quote and schedule reflect the real rewrite list.

Rollback has to be planned before the production migrate starts because bench migrate changes the database schema and transforms data in place. Reverting the apps to their v15 commits does not undo those changes, so a site left on v16 code with a v15 database, or the reverse, will fail in ways that are hard to diagnose. The only dependable way back is to restore the backup taken immediately before the maintenance window onto a v15 bench with matching app versions. This section covers what that backup must contain, how to prove it works, how long the old environment stays available, and who decides between rolling back and fixing forward.

The rollback point is a full bench backup taken after the site enters maintenance mode and after the final pre-cutover sync of transactions, so no writes occur between the backup and the migrate. It should include the database, the public and private files, and a written record of the exact ERPNext and Frappe releases and the commit of each custom app. Store that record with the backup, because a restore is only useful if the team can rebuild the same v15 bench that produced it. Before starting the migrate, confirm the backup set is complete, and keep a copy off the upgrade host so a failure there cannot remove both the live site and the rollback point.

A backup that has never been restored is an assumption, not a rollback point. During the staging rehearsal, restore the pre-migrate backup to a separate v15 bench, start the site, log in, and check a sample of recent sales invoices, payment entries and stock ledger entries against the values recorded before the rehearsal migrate. Time each step: taking the backup, copying it, restoring the database, restoring the files, rebuilding the v15 bench and reaching the first successful login. These measurements define the rollback window you can responsibly commit to. Ask the partner to state in writing the restore procedure, the evidence they will produce from the rehearsal, and who runs the restore during the window.

Keep the v15 environment intact until the business has signed off the v16 site and the agreed post-cutover monitoring period has closed. That period, along with the hosting and storage cost of keeping the old bench and backups available, belongs in the plan and the quote, not in an assumption. Set decision criteria before the window opens. Roll back if the migrate fails and cannot be repaired within the agreed window, if reconciliation of ledgers, stock balances or open documents shows differences that finance cannot explain, or if a custom app or script breaks a core process with no safe fix. Fix forward when the problem is contained, reversible and does not touch financial data. Name one person with authority to call the rollback, a finance approver for ledger decisions, and an escalation path agreed in advance.

Keep the version 15 backup, the bench directory and the v15 environment intact until the exit point written into the upgrade scope. That exit point should be a named decision made by the business, recorded with the person who approved it. Until then, keep a restorable copy of the v15 database, the sites folder, the apps list and the site configuration files, and confirm that a restore to a separate host has actually been tested. Record where the backup is stored, who can access it and how it is kept off the production network. Ask your partner or internal team to confirm how long the v15 environment will stay powered on and who has authority to retire it, because that approval is what closes the rollback window.

Monitoring after cutover should cover three places where failures usually appear first: scheduled jobs, background workers and custom code. Review the Scheduled Job Log and the Error Log DocType daily during the first weeks, and check the bench logs for worker and scheduler errors. Pay particular attention to Server Scripts. From version 15 they are disabled by default and need the server_script_enabled setting, so confirm which scripts are enabled on the migrated site, whether each one still runs, and whether any call from a custom app or an integration now fails without an obvious message to the user. Set alerts on repeated failures of the same job, since one recurring error often points to a broken integration.

Both supported lines receive frequent minor releases, so the post-upgrade plan needs a standing testing routine. The frappe/erpnext releases page lists v16.51.1 as published on October 15, 2026 and v15.123.0 on October 14, 2026, which shows the pace on both lines. Apply each minor release first to a staging copy built from a recent production backup. Run the custom app test cases and the critical document flows, such as sales invoices, stock entries and payroll runs, and only then promote the release to production. Read each release note for changes that touch Server Scripts or custom app hooks. Keep staging on the same release as production so that test results remain comparable, and agree a review rhythm with your partner before go-live.

Document the upgrade as it happens rather than reconstructing it afterwards from memory. The record should hold the final app versions and the commit or tag used for each custom app, the migration log with start and end times and any errors, the data check results with reconciliation totals for ledgers, stock and open documents, and every decision taken during cutover with the person who approved it. For each custom app, name one owner who answers for its code, its test cases and its next upgrade. Store the record alongside the v15 backup so both can be read together during any later investigation. For support, upgrades and retainer options after this point, see the ERPNext upgrades and support page.