ERPNext Migration Guide — v13 → v14 → v15

Edit Page New Page Revisions

Purpose: Standardized, step-by-step migration procedure for upgrading Frappe / ERPNext from v13 to v15 (via v14). This is written to be generic, low-risk, and to help teams plan, test, and execute the upgrade across environments (dev → staging → production).

Table of contents

  1. Scope & high-level summary

  2. Two supported approaches (recommended + rebuild-from-scratch)

  3. Pre-requisites (environment, packages, backups)

  4. Pre-upgrade checklist (site & code audit)

  5. Upgrade steps (13 → 14, then 14 → 15) — staging first

  6. Post-upgrade checks & verification

  7. Common errors (per phase) and quick fixes

  8. Appendix: useful commands & notes

1. Scope & high-level summary

This guide targets the safe upgrade path from ERPNext v13 to v15 by performing incremental upgrades (v13 → v14 → v15). Upgrading across two major releases in one jump is not recommended: migrating via the intermediate major release helps run migration scripts and database patches in the intended sequence.

Two supported approaches are described below:

  • Approach A — In-place sequential upgrade (recommended for smaller/customization-light instances): Upgrade the existing site by changing branches and running the official migration steps, first to v14 and then to v15. This keeps site data and custom apps intact but may surface git conflicts and compatibility issues.

  • Approach B — Rebuild from scratch + data migration (recommended when core apps were modified, many incompatible customisations, or when you want a clean baseline): Provision a new server with target versions, install fresh apps, port customizations to separate custom apps (or reimplement), and then migrate data. This is safer when the production instance has core changes or heavy hacks.

Important note (core-app changes / git conflicts): If your team has modified core apps (frappe/erpnext) directly, the git operations during an in-place upgrade can produce large conflicts. Resolving those may be very time consuming. Prefer Approach B in such cases — extract business logic/customizations into a separate app and keep core apps pristine.

2. Two approaches — pros & cons

Approach A — Sequential in-place upgrade (v13 → v14 → v15)

Pros: Easier if you have limited customizations; preserves site files and settings. Faster when custom apps are already version-compatible.

Cons: Risk of merge conflicts with local core modifications; migration scripts can fail due to incompatible custom fields or doctypes; may require many hotfixes.

Approach B — Rebuild from scratch and migrate data

Pros: Clean baseline, avoids core-git conflicts, forces modern architecture and best practices, easier long-term maintenance.

Cons: More upfront work: porting/rewriting customizations, re-testing all business flows, potential data mapping work during migration.

3. Pre-requisites (environment & packages)

Always perform these steps on a staging copy first. Never run a production upgrade without a fully tested staging run.

Common environment requirements (verify exact versions for target Frappe/ERPNext releases):

  • Ubuntu / Debian LTS recommended. Check official docs for version compatibility.

  • Python 3.x (match the version required by target release) — create and use a virtualenv.

  • Node.js (LTS) and yarn (for building assets)

  • MariaDB / MySQL compatible version and proper configuration (innodb, etc.)

  • Redis (cache, queue)

  • wkhtmltopdf (and patched build) if PDF printing required

  • Bench CLI (compatible with your Frappe version)

  • Supervisor / systemd configs for processes

  • Nginx (or OpenLiteSpeed) configs

  • Backups and snapshots capability (filesystem & DB)

Before any upgrade, compile an environment inventory (server OS, Python version, MariaDB version, bench version, installed apps & versions, custom apps list).

4. Pre-upgrade checklist

  • Full backup of site: DB + files + public/private folders + sites/apps folder.

  • Git snapshot (or create tarball) of the frappe-bench / sites directory.

  • Create a staging environment (copy DB + files) and validate staging works.

  • Inventory of customizations:

    • Custom apps (list with repo and current branch)

    • Any direct changes inside apps/frappe or apps/erpnext (note file paths & diffs)

    • Custom fields, custom doctypes, server scripts, custom print formats

  • Document installed third-party apps and their compatibility with v14/v15

  • Ensure you have access credentials for server, DB, and Git repos

  • Prepare a maintenance/downtime window for production migration

  • Notify stakeholders and QA for acceptance testing

Backup examples:

# site backup via bench
cd /home/frappe/frappe-bench
bench --site site1.local backup --with-files
# creates public/backups/<timestamp>-site1.local.sql.gz and files

# filesystem snapshot (if using cloud provider)
sudo tar -czf /backups/frappe-bench-$(date +%F).tgz /home/frappe/frappe-bench

# mysqldump (alternative)
mysqldump -u root -p --databases `grep 'db_name' -m1 -A0 sites/common_site_config.json` > /backups/site1.sql

5. Upgrade steps (detailed)

These are recommended, general steps. Always test on staging and read the release notes and migration notes for each target version.

A. Prepare staging copy

  1. Restore DB and files to a staging server.

  2. Validate the staging instance is working as expected.

  3. Pin the current branches (v13) for frappe and erpnext in staging so you can reproduce a rollback.

B. Upgrade path: v13 → v14 (staging)

  1. Update bench & dependencies on staging:

# inside bench dir
pip install --upgrade frappe-bench bench
bench --version

  1. Fetch upstream branches and switch apps to v14 branch:

cd apps/frappe
git fetch --all
git checkout version-14  # or the exact branch name used by your deployment
cd ../erpnext
git fetch --all
git checkout version-14

  1. If you maintain custom apps, check compatibility and update their app_version / code where needed. If custom apps import frappe/erpnext modules, adjust imports.

  2. On bench root:

bench update --patch  # runs patches. If you need to rebuild assets, add --build
bench --site site1.local migrate
bench --site site1.local clear-cache
bench build
bench restart

If bench update complains about local changes in frappe/erpnext:

  • Option 1: If changes are accidental, reset to remote with git reset --hard origin/version-14 in each app. WARNING: this discards local changes.

  • Option 2: If changes are intentional, you must re-implement them as a separate custom app or create patches, then proceed.

  1. Run site-specific checks: login, run tests for key workflows, check custom print formats, custom scripts, and reports.

  2. Fix issues discovered, run any missing patches, and re-run bench migrate until clean.

C. Upgrade path: v14 → v15 (staging)

Repeat the same process for v15:

cd apps/frappe && git fetch --all && git checkout version-15
cd ../erpnext && git fetch --all && git checkout version-15
bench update --patch --no-backup  # on staging, ensure migrations run
bench --site site1.local migrate
bench build
bench restart

  1. Re-test all business flows, background jobs, scheduler jobs, API endpoints, integrations, and reports.

  2. Prepare a migration runbook for production with exact commands used in staging and a verified backup.

6. Post-upgrade verification checklist

  • Login as admin and a sample end-user

  • Verify critical doctypes and workflows (sales, purchase, accounting ledgers)

  • Run scheduled jobs and verify no errors in worker logs

  • Check bench logs / supervisor logs for errors

  • Validate attachments, website pages, emails, and PDF generation

  • Run API smoke tests for external integrations

  • Validate custom reports and print formats

  • Run a small set of end-to-end business transactions and confirm data integrity

7. Common errors & suggested fixes

Below are common issues surfaced during major upgrades and pragmatic fixes.

1) Git conflicts / local changes in core apps

Symptoms: bench update fails with "Your local changes to the following files would be overwritten..." or git merge conflicts.

Fixes:

  • If changes are not needed, reset to upstream branch:

    git fetch origin
git reset --hard origin/version-14

  • If changes are required business logic, extract changes into a custom app and remove local changes from apps/frappe or apps/erpnext.

  • If you must keep local changes, perform careful 3-way merges in a dev branch and test thoroughly. Expect non-trivial effort.

Prevention: Keep core apps untouched; implement custom logic via separate apps.

2) Migration script failures (missing columns, unique constraint errors)

Symptoms: bench migrate or patch scripts raise DB errors about missing columns, duplicates, or modified schema.

Fixes:

  • Inspect the failing patch in frappe.utils / patch script. Manually correct data if required (e.g., remove duplicates, add missing default values), then re-run the patch.

  • Export DB, create a small reproducer and run the patch locally to iterate.

3) Build / assets failure (node/yarn related)

Symptoms: bench build fails with node or yarn errors.

Fixes:

  • Ensure Node LTS and yarn are installed. Remove node_modules and rebuild:

    rm -rf node_modules
yarn install
bench build

4) Missing dependencies (Python packages)

Symptoms: ImportError or module not found in logs.

Fixes:

  • Activate the bench virtualenv and install requirements from requirements.txt for frappe/erpnext.

    source env/bin/activate
pip install -r apps/frappe/requirements.txt
pip install -r apps/erpnext/requirements.txt

5) wkhtmltopdf / PDF generation

Symptoms: PDF generation fails or output is blank.

Fixes:

  • Install the patched wkhtmltopdf build supported by Frappe for your distro and architecture.

6) Custom fields / scripts break

Symptoms: UI errors or missing fields after migration.

Fixes:

  • Export custom fields and server scripts from old site, inspect for API changes, update them and re-import.

  • Consider moving critical customizations into a maintained custom app.

8. Appendix: Useful commands & notes

General bench / git commands

# backup
bench --site site1.local backup --with-files

# restore
bench --site site1.local --force restore /backups/site1.sql.gz

# migrate
bench --site site1.local migrate

# build assets
bench build

# restart
bench restart

# check logs
bench --site site1.local logs

# reset app to remote branch
cd apps/frappe
git fetch --all
git reset --hard origin/version-14

Notes & best practices

  • Keep core apps (frappe/erpnext) pristine — no direct edits. Use a custom app for overrides and custom behaviour.

  • Maintain an offsite backup and at least one snapshot just before production cutover.

  • Document each fix applied in staging so it can be reproduced during production run.

  • If there is heavy customization, strongly prefer Approach B (rebuild + migrate) to avoid long conflict resolution.

  • Mabe loss the data so always be backup

  • not recomended for production server do with dev server

  • if in core we have edited the code which make very bigger git conflicts

Document generated as a generic migration runbook. Replace placeholders with environment-specific values and team contacts before executing on production.


Previous Page

Left

Next Page

Right

On this page