/frappe-ops-upgrades

name: frappe-ops-upgrades
description: >
  Use when upgrading Frappe/ERPNext between major versions (v14 to v15, v15 to v16), troubleshooting failed migrations, or planning rollback.
  Prevents broken upgrades from skipped patches, incompatible customizations, and missing pre-upgrade checks.
  Covers version upgrade paths, bench update, migrate command, patch troubleshooting, rollback procedures, breaking changes per version.
  Keywords: upgrade, migration, v14, v15, v16, bench update, bench migrate, rollback, patches, breaking changes, update failed, bench update error, migration error, patches failing, rollback after upgrade..
license: MIT
compatibility: "Claude Code, Claude.ai Projects, Claude API. Frappe v14-v16."
metadata:
  author: OpenAEC-Foundation
  version: "2.0"

Version Upgrades

Complete guide for upgrading Frappe/ERPNext between major versions, handling failed migrations, and rolling back safely.

**Versions**: v14 → v15 → v16

---

Quick Reference: Upgrade Commands

| Task | Command | |------|---------| | Full update | `bench update` | | Update specific app | `bench update --pull --app erpnext` | | Switch branch | `bench switch-to-branch version-15 frappe erpnext` | | Run migrations only | `bench --site mysite migrate` | | Check migration readiness | `bench --site mysite ready-for-migration` | | Backup before upgrade | `bench --site mysite backup` | | Restore from backup | `bench --site mysite restore /path/to/backup.sql.gz` | | Re-run failed patch | Add `#YYYY-MM-DD` suffix in patches.txt |

---

Decision Tree: Upgrade Strategy

Need to upgrade?
├── Single minor version bump (e.g., v15.10 → v15.20)?
│   └── YES → Run `bench update` directly
├── Major version jump (e.g., v14 → v15)?
│   ├── Have custom apps?
│   │   ├── YES → Test on staging FIRST, check breaking changes
│   │   └── NO → Follow standard upgrade path
│   └── Multiple major versions (v14 → v16)?
│       └── ALWAYS upgrade one version at a time: v14 → v15 → v16
└── Production environment?
    ├── YES → ALWAYS test on staging clone first
    └── NO → Proceed with standard upgrade

---

Pre-Upgrade Checklist

**ALWAYS** complete these steps before ANY major version upgrade:

1. **Full backup** — `bench --site mysite backup --with-files` 2. **Test on staging** — Clone production to a staging bench and test there first 3. **Check breaking changes** — Review the breaking changes section below 4. **Audit custom apps** — Run custom apps against new version's API changes 5. **Check Python/Node versions** — v15 requires Node 18+; v16 requires Node 24+, Python 3.14+ 6. **Disable scheduler** — `bench --site mysite scheduler disable` 7. **Check pending jobs** — `bench --site mysite ready-for-migration` 8. **Read release notes** — Check GitHub release notes for each version

---

Standard Upgrade Process

Step-by-Step

# 1. Backup all sites
bench backup-all-sites

# 2. Switch to target version branch
bench switch-to-branch version-15 frappe erpnext

# 3. Update (pulls code, installs deps, builds, migrates)
bench update

# 4. Verify
bench --site mysite migrate  # if not done by update
bench version                # confirm versions

What `bench update` Executes (In Order)

1. Backup all sites 2. Pull latest code for all apps (`git pull`) 3. Install Python requirements (`pip install`) 4. Install Node requirements (`yarn install`) 5. Build static assets (`bench build`) 6. Run migrations on all sites (`bench migrate`) 7. Restart bench processes

---

v14 → v15 Breaking Changes

Environment Requirements

| Requirement | v14 | v15 | |-------------|-----|-----| | Node.js | v14+ | **v18+** | | Python packaging | setup.py | **pyproject.toml** |

Backend Breaking Changes

• **`db.set()` removed** — Use `doc.db_set()` instead
• **`db.sql()` parameters removed** — `as_utf8` and `formatted` no longer accepted
• **`db.set_value()` for Singles** — Use `frappe.db.set_single_value()` instead
• **`job_name` deprecated** — Use `job_id` parameter in `enqueue()`
• **`frappe.new_doc()` arguments** — `parent_doc`, `parentfield`, `as_dict` MUST be keyword args
• **`frappe.get_installed_apps()`** — No longer accepts `sort` or `frappe_last` args
• **Method override order reversed** — Last override now takes precedence
• **Timezone functions renamed** — `convert_utc_to_user_timezone` → `convert_utc_to_system_timezone`

Frontend Breaking Changes

• **Vue 2 → Vue 3** — All Vue components MUST be migrated
• **Window globals removed** — `get_today` → `frappe.datetime.get_today`, `user` → `frappe.session.user`
• **`this` in Client Scripts** — Local scope access no longer supported
• **Image lazy loading** — Replace `website-image-lazy` class with native `loading="lazy"`

Security Changes

• **Server Scripts disabled by default** — Enable: `bench set-config -g server_script_enabled 1`
• **"Desk User" role added** — Replaces "All" role for desk user permissions
• **`currentsite.txt` removed** — Use `bench use sitename` or `FRAPPE_SITE` env var

Removed Features

• Event Streaming moved to separate app
• Cordova support removed
• `setup.py` removed (use `pyproject.toml`)
• `--make_copy` and `--restore` build flags removed (use `--hard-link`)

See [breaking-changes.md](references/breaking-changes.md) for the complete list.

---

v15 → v16 Breaking Changes

Environment Requirements

| Requirement | v15 | v16 | |-------------|-----|-----| | Node.js | v18+ | **v24+** | | Python | 3.10+ | **3.14+** |

Backend Breaking Changes

• **Default sort order changed** — `creation` instead of `modified` for all list queries
• **`has_permission` hooks** — MUST return explicit `True`; `None` no longer accepted
• **`frappe.get_doc(doctype, name, field=value)`** — No longer updates values
• **DB commits in document hooks** — No longer allowed to prevent data integrity issues
• **`frappe.sendmail(now=True)`** — No longer commits transactions implicitly
• **`db.get_value()` for Singles** — Now