Upgrade ERPNext from v5 to v13

Why ?

My ERPNext venture has been halted for a long while. However, we do have an existing customer to support.
They have been using the system for a long while without any issue. However, no upgrade means no new features and this time they are really in need of that

First attempt - total failure …

So the first thing I’ve tried was just going head on with upgrading (on a brand new clone of the server, of course).
And it turned out … terribly. How’s so ?

  • If there are custom change on your erpnext repository, you have to reset it to master branch first
  • If you have custom modules, of course, disable them first
  • Script to upgrade then run based on your current database and the amount of changes are crazy
  • v5 was using python2 and v13 is using python3 (of course)
  • There is no minimal success baseline for you to build upon. Everything just failed.

In fact, after spending a few days on this, I was about to give up all together…

Second attempt - finally see some lights

Now, breathe and take a step back. This is not the only (real) way.

  • Back up the data (the database and the media files)
  • Back up the changes you have customised on
  • Install the completely new version
  • Restore the database on this new instance
  • Run migrations (–skip-failure)
  • Try to fix migration issues one by one
  • Manually migrate certain data that has been changed
  • Reapply changes from modules and customizations

Steps that I have taken

  1. Back up old Instance bench backup —with-files
  2. Install new install v13 vanila
  3. Download all files to new instance and make sure have enough space. So that when you restore it doesn’t fail because not enough space.
  4. bench mariadb and Repair table in mariadb
  5. Then restore the database and files with
    bench restore path/to/sql --with-public-files path/to/public_files.gz --with-private-files path/to/private_files.gz
  6. Migrate but skipp all failed migrations: bench migrate —skip-failing From here on it depend on what errors will you encounter.
  7. Set Email Account uidnext = 0
set sql_safe_updates = 0;
update `tabEmail Account` set uidnext = '0' where trim(coalesce(uidnext, '')) = '';
set sql_safe_updates = 1;
  1. Delete Custom Field sales_uom -> might want to copy data
select * from `tabCustom Field` where name like '%sales_uom%';
delete from `tabCustom Field` where name = 'Item-sales_uom';
delete from `tabCustom Field` where name = 'Item-purchase_uom';
  1. Quotation Item: Copy Stock UOM to UOM for existing items
set sql_safe_updates = 0;
update `tabQuotation Item` set uom = stock_uom;
set sql_safe_updates = 1;
  1. Solve patch issue Patch: erpnext.patches.v11_0.create_salary_structure_assignments
pymysql.err.OperationalError: (1054, "Unknown column 'sse.from_date' in 'field list'")


alter table `tabSalary Structure Employee` add column (from_date DATETIME DEFAULT current_timestamp(), to_date DATETIME DEFAULT current_timestamp());
set sql_safe_updates = 0;
update `tabSalary Structure Employee` set from_date = '2021-01-01 00:00:00';
update `tabSalary Structure Employee` set to_date = '2021-12-31 00:00:00';
set sql_safe_updates = 1;
  1. Solve patch issue:

Patch: erpnext.patches.v12_0.move_item_tax_to_item_tax_template


insert into `tabSingles` (doctype, field, value) values ('Accounts Settings', 'allow_stale', 1);
insert into `tabSingles` (doctype, field, value) values ('Accounts Settings', 'stale_days', 2);
  1. Solve patch issue Patch: erpnext.patches.v13_0.rename_issue_doctype_fields Fix:
update `tabIssue` set resolution_by_variance = 1;
update `tabIssue` set response_by_variance = 1;
  1. After fixing all patch issues, run bench migrate again without --skip-failing
  2. Install vuejs npm install vue (first time)
  3. Run bench update bench update —reset
  4. Remember to enable scheduler bench --site all enable-scheduler

At this point, hopefully you would also have a working version of new ERPNext v13 already. To be honest, that was a lot of hours (even days) of mine. And I hope someone else can find that useful.

Of course, the biggest lesson would be update earlier when the work is not too intimidating…


Written on August 24, 2021