Switching Branch and Tag of ERPNext from Develop to 14.x.x

While setting up a new Frappe development server, I encountered a common mistake that caused significant issues. The live server was running Frappe v14 and ERPNext v14, but while creating the dev server, I mistakenly installed ERPNext on the develop branch instead of version-14.

Without noticing this mismatch, I restored the database backup from the live server. After a successful restoration, attempting to migrate the database resulted in multiple errors, such as missing modules and missing doctypes.

Uninstalling and reinstalling ERPNext would have deleted all the data, requiring another backup restoration. To avoid wasting time, I followed a structured approach to switch the branch correctly without data loss. Below are the steps I took.

Step 1: Verify Your Current Setup

Before making any changes, check which branch you’re on:

cd ~/frappe-bench/apps/erpnext
git branch

If you see develop or another branch, you’ll need to switch to version-14.

Additionally, verify your remote repository:

git remote -v

Make sure you’re fetching from the correct repository (upstream or origin).

Step 2: Fetch the Latest Tags & Branches

Since version 14 is tagged, first fetch all updates:

git fetch --all --tags

Then, list available tags:

git tag --sort=-creatordate

Look for a tag like v14.31.1.

Step 3: Checkout ERPNext Version 14

Once you confirm that v14.31.1 exists, switch to it:

git checkout -b version-14 v14.31.1

To verify the switch:

git branch

You should now see:

  develop
* version-14

Step 4: Switch Frappe to Version 14

Since ERPNext relies on Frappe, you must also switch your Frappe repository to version-14:

cd ~/frappe-bench/apps/frappe
git fetch --all --tags
git checkout -b version-14 v14.31.1

Confirm the branch:

git branch

Step 5: Apply Migrations and Update Dependencies

Now that both ERPNext and Frappe are on version 14, update the system:

cd ~/frappe-bench
bench update --patch
bench migrate
bench restart

This ensures your database schema is updated and everything works smoothly.

Step 6: Verify the Upgrade

Run the following command to check the installed versions:

bench version

Expected output:

erpnext 14.x.x
frappe  14.x.x

If everything looks good, restart your bench:

bench start

Now, open ERPNext in your browser at:

http://localhost:8000

or your server’s domain.

Troubleshooting

Unstaged Changes Error

If bench update --patch fails due to unstaged changes, reset them:

cd ~/frappe-bench/apps/erpnext
git reset --hard
cd ~/frappe-bench/apps/frappe
git reset --hard

Then retry:

bench update --reset

Missing Dependencies

If bench update --patch fails due to missing dependencies, install them:

bench setup requirements
bench update --patch

Final Thoughts

By following these steps, I successfully switched ERPNext from the develop branch to version-14 without losing data. Mistakes like installing ERPNext on the wrong branch can happen, but by following a structured recovery approach, you can avoid unnecessary reinstallation and data loss.

Always verify the branch before restoring backups!

If you encounter any issues, let me know in the comments! 🚀