Upgrading an Old ERPNext: What Breaks and How to Plan It

Why an old version is a business risk

The system keeps running, so the risk is easy to ignore until something breaks, or until a new requirement needs a supported version.

What breaks, and what doesn't

Standard features rarely cause trouble. Most of what breaks is built around them, or has moved out of ERPNext:

• Custom code. Scripts, reports and custom apps written for the old version. At one manufacturer, delivery notes stopped saving after an upgrade because a custom weight calculation came out as zero. It was reported and fixed the same day.
• Print formats. Major versions sometimes change how data is stored. On one upgrade, serial and batch numbers moved, so every invoice and delivery note that printed them had to be rebuilt.
• Modules that left ERPNext. Frappe has moved modules such as HR and payroll, lending and payments into separate apps. If you use one, its app has to be installed as part of the upgrade.
• Changes made on the live system. Customisations made in ERPNext's own settings screens, outside any app, can clash with the new version. One production upgrade we ran stopped part-way on exactly this and couldn't finish until the clash was cleared. Afterwards we moved that client's customisations into its own app, so the next upgrade carries them.

How we plan an upgrade

1. Take stock first. The version, every custom app and script, and which moved modules you use. For one manufacturer with heavy customisation, the upgrade plan listed 22 custom scripts, two dashboards, a scheduled job and an override of standard code, each with its own test.
2. Run it on a copy. The upgrade runs to the end on a copy of your live system, so anything that fails, fails there.
3. Test a full cycle on the copy. Purchase, stock entry, sale and payment, plus every print format your team uses.
4. Clean up as you go. On each upgrade we remove custom fields and print formats that ERPNext now covers itself, so the next one has less to test.

In place, or a fresh start?

Not every upgrade has to carry every old transaction. When a system has years of clutter, loading master data and opening balances into a fresh site can be cleaner than upgrading it in place. Metro Tech Pipe Industries took that route once in nine major versions.

What it costs

A major version upgrade isn't part of a support plan; it's quoted at a fixed price before work starts. The price depends on how far behind you are and how much custom work has to be tested and fixed, which is why we check the system first.

Not sure how far behind you are? The free health check starts with a 30-minute call, then tells you your upgrade path and what will break, and ends in a fixed-price quote.