Start Free عربي
Technical Tutorials 2026-04-05 14 min read

Updating ERPNext v15: What Every Command Does and What Can Go Wrong

ERPNext updates fall into three categories, each with completely different risk levels. Category 1: Minor patches (v15.22 → v15.26) — low risk, done in 15 minutes. Category 2: Major version upgrade (v14 → v15) — high risk, requires staging environment, plan for 4-8 hours. Category 3: Framework update (Frappe core changes) — medium risk, follow the same process as minor patches but read the release notes first. The most expensive mistake developers make is treating a major version upgrade like a minor patch. This guide shows you how to handle each one correctly.

The Golden Rule: The Backup You Take Before Updating Is Your Insurance Policy

Non-Negotiable: Do This Before Every Update

Every update must start with a verified backup. Not a backup you assume exists — a backup you just took and confirmed the file exists on disk. One corrupted update without a backup = permanent data loss. There is no undo button in a database.

bash 
# Take a complete backup before EVERY update (run as frappe user)
cd ~/frappe-bench
bench --site mycompany.com backup --with-files

# Confirm the backup file actually exists and has content
ls -lh sites/mycompany.com/private/backups/
# You should see a .sql.gz file created in the last 2 minutes
# It should be more than 1 KB — a 0 byte file means the backup failed

# Get the exact filename for use in rollback if needed
ls -t sites/mycompany.com/private/backups/*.sql.gz | head -1

Copy the backup to an external location BEFORE starting the update:

bash 
# Copy to another server via SCP
scp sites/mycompany.com/private/backups/*.sql.gz user@backup-server:/backups/

# Or upload to S3 (if you have AWS CLI configured)
aws s3 cp sites/mycompany.com/private/backups/*.sql.gz s3://your-backup-bucket/erpnext/

Scenario A: Minor Patch Update (v15.x → v15.y) — Low Risk, 15 Minutes

Minor patches fix bugs and security issues within the same major version. They almost never break existing functionality. This is the update you run most often — ideally weekly or bi-weekly.

What happens when you run 'bench update': (1) Git pulls the latest commits for all installed apps, (2) Python dependencies are updated if requirements.txt changed, (3) Database migration scripts run if any schema changes exist, (4) JavaScript/CSS assets are rebuilt.

bash 
# Step 1: Take backup (already covered above)

# Step 2: Check what version you are currently on
bench version
# Note this down — you will need it for rollback if something fails

# Step 3: Run the update
bench update --pull

# If you want to run migration separately (safer for large databases):
bench update --pull --skip-migrate
bench --site mycompany.com migrate  # Run migration while you can monitor it

# Step 4: Restart all services to load new code
bench restart

# Step 5: Verify the update succeeded
bench version  # Should show the new version numbers
bench --site mycompany.com doctor  # Checks for any inconsistencies
How to Know the Update Worked

After restart: log into ERPNext, open a Sales Invoice and a Purchase Order, check that the dashboard loads. If anything looks broken or throws an error, proceed to the rollback steps immediately.

Scenario B: Major Version Upgrade (v14 → v15) — High Risk, Use a Staging Environment

Do Not Do This on Production Without Testing on a Clone First

A v14 to v15 upgrade changes database table structures (schema migrations), removes deprecated APIs that custom code may use, and can break custom print formats and custom fields. Testing on a staging environment with a copy of your real data is not optional — it is the only way to know what will break before it breaks in production.

Step 1: Set up a staging environment. This is a completely separate server (or a server you can afford to break) with a copy of your production database.

bash 
# ON YOUR STAGING SERVER (not production!)
# Repeat the full installation from the installation guide first
# Then restore your production backup onto the staging site:

bench new-site staging.mycompany.com \
  --mariadb-root-password DB_PASSWORD \
  --admin-password ADMIN_PASSWORD

# Restore the production database backup onto staging
bench --site staging.mycompany.com restore \
  /path/to/your-production-backup.sql.gz

Step 2: Switch the staging environment to v15 and test the upgrade:

bash 
# Switch all apps to the v15 branch
bench switch-to-branch version-15 frappe erpnext hrms

# Update and run migrations
bench update --pull

# If errors appear during migration, they will appear here on staging
# This is exactly why you test here first

Step 3: Test these critical functions on staging BEFORE touching production: (1) Log in and verify the dashboard loads without JavaScript errors — open browser console (F12) and look for red errors. (2) Open an existing Sales Invoice from before the upgrade. Verify all fields are visible and correct. (3) Create a new test Sales Invoice and submit it. Verify it posts correctly. (4) Run the Trial Balance report for last month. Verify the numbers match what you had before the upgrade. (5) Open a custom print format if you have any. Verify it still renders correctly. (6) Test e-invoicing submission (ETA/ZATCA) with a test invoice if applicable. (7) Test the POS if your business uses it.

Step 4: If all tests pass on staging, apply to production during a maintenance window (low traffic hours):

bash 
# ON PRODUCTION SERVER
# Schedule a maintenance window (e.g., 2 AM Friday)

# 1. Take final backup just before the upgrade
bench --site mycompany.com backup --with-files

# 2. Put the site in maintenance mode so users cannot access during upgrade
bench --site mycompany.com set-maintenance-mode on

# 3. Switch to v15 branches
bench switch-to-branch version-15 frappe erpnext hrms

# 4. Pull code and run migrations
bench update --pull

# 5. Rebuild assets for the new version
bench build --production

# 6. Restart services
bench restart

# 7. Disable maintenance mode
bench --site mycompany.com set-maintenance-mode off

# 8. Verify everything is working
bench version
bench --site mycompany.com doctor

Scenario C: Rollback After a Failed Update — How to Undo in an Emergency

If the update fails and your site is broken, here is how to get back to the working state. Speed matters here — every minute your system is down costs business. Keep this section bookmarked.

bash 
# Step 1: Stop all services immediately
sudo supervisorctl stop all

# Step 2: Switch all apps back to the previous version branch
# If you were on v15 and upgrading to v16:
bench switch-to-branch version-15 frappe erpnext hrms

# If you were on v14 and upgrading to v15:
bench switch-to-branch version-14 frappe erpnext hrms

# Step 3: Restore the database from the backup you took before updating
# Replace the backup filename with the actual file you saw in 'ls' earlier
bench --site mycompany.com restore \
  sites/mycompany.com/private/backups/20260405_020000-mycompany_com-database.sql.gz

# Step 4: Rebuild assets for the old version
bench build

# Step 5: Start services
sudo supervisorctl start all

# Step 6: Test the site is working
bench --site mycompany.com doctor
Data Loss Warning on Rollback

Any transactions created AFTER the backup was taken will be lost during rollback. This is unavoidable. It is why the backup must be taken immediately before the update — not the night before. Every hour between backup and update = potential data loss during rollback.

How to Check What Changed Before Updating (Read Release Notes Like a DevOps Engineer)

Before any update, spend 5 minutes reading the release notes. This tells you if the update changes anything you depend on.

bash 
# See what commits are incoming before pulling them
git -C apps/erpnext log --oneline HEAD..origin/version-15 | head -20
git -C apps/frappe log --oneline HEAD..origin/version-15 | head -20

# Check if any migration files exist (schema changes = more risk)
ls apps/erpnext/erpnext/patches/
# New patch files since your last update = database will be modified

Why Managed SaaS Handles This Better

Everything above is real operational work that a DevOps engineer must do correctly every time. On Managely Cloud, every ERPNext update is tested in a sandbox environment against a snapshot of your actual data before being applied. When it is safe, it is deployed during low-traffic hours. You receive a notification that your system is updated. You did nothing. You were never at risk of data loss.

Zero-Risk Updates

Managely tests every update against real data patterns before deployment. Major version upgrades are staged, verified, and applied without any action required from you. Tax compliance updates (ETA, ZATCA, FTA) deploy automatically the same day governments release new requirements.

Leave a comment

Comments

Skip the maintenance windows and rollback anxiety. Get zero-risk automatic updates on Managely Cloud.