When a custom app stops building after a v15 to v16 upgrade, it is usually one of six things, in this order: the host or image is on Python 3.11 when v16 needs 3.14, Node is on 22 when v16 needs 24+, your has_permission hook returns None instead of True, your hooks.py commits inside a document event, a frappe.db.get_value() comparison fails because v16 casts Single DocType values to native types, or you call a function v16 removed. Each worked on v15 and breaks on v16. This post walks the fix for each.
Most v16 upgrade tickets we take start the same way: a working custom app, a clean bench, and a bench install-app that dies at the first import. The failure modes are finite. I lead ERPNext and Frappe upgrades at MithTech, a team of Frappe specialists in Bengaluru. This is the ladder we walk before we touch a line of the client's app code.
Why does a custom Frappe app fail to build on v16?
Answer
Usually an environment mismatch or one of a small number of API changes in frappe. Python 3.14 and Node 24 are hard prerequisites, has_permission hooks must return True, hooks.py document events can no longer commit, and a handful of functions were removed. Each has a distinct error signature, and none requires rewriting your app.
Frappe's Migrating to version 16 wiki is the source for the API changes below. The ladder takes the causes in the order they usually fire during bench install-app or the first request after bench migrate.
This post is part of the Frappe and ERPNext Architecture Guide. Its hooks chapter explains which hook runs when, and why a commit inside a document event does nothing on v16.
Is your Python or Node too old for v16?
v16 requires Python 3.14 and Node.js 24+ (Frappe's pyproject.toml on the version-16 branch pins >=3.14,<3.15; package.json asks for Node >=24). If either is older, the failure looks unrelated:
- Python 3.11 to 3.13: pip refuses to install Frappe ("requires a different Python"), or an existing virtualenv fails on the first
import frappewith a traceback inside Frappe, not your app. - Node 22 or below:
bench build(or the assets step in a Docker build) fails with an engine or parse error deep inside the JavaScript toolchain, again pointing at Frappe's assets, not yours.
Check both first:
On Ubuntu 22.04 or 24.04, install Python 3.14 from deadsnakes and Node 24 from NodeSource; the distribution packages ship Python 3.10 or 3.12 and a much older Node. Rebuild the bench virtualenv against the new Python before anything else:
Which hooks.py changes silently break a custom app on v16?
has_permission must return True explicitly. Every custom permission hook of the shape below is now wrong on v16:
# v15: worked because None was treated as "allow"
def has_permission(doc, ptype, user):
if some_condition(doc, user):
return True
# implicit None → v15: allow, v16: silently deny
On v16 the contract is strict: True allows, False denies, and None denies. Any hook that returns nothing on the fall-through path now denies every user who reaches that path, without an error. Grep your custom app for def has_permission and audit each one.
Document hooks cannot commit transactions. Frappe's notes say document hooks set up in hooks.py can no longer commit, to protect data integrity. If a doc_events handler called frappe.db.commit() inside on_submit, on_update or after_insert, that commit no longer does what it did. The pattern:
# hooks.py
doc_events = {
"Sales Invoice": {
"on_submit": "your_app.utils.push_to_external"
}
}
# your_app/utils.py — this used to work on v15
def push_to_external(doc, method):
call_external_api(doc)
frappe.db.commit() # ← not supported in a document hook on v16
If the side effect must survive a rollback of the document's transaction, move it into a background job:
def push_to_external(doc, method):
frappe.enqueue("your_app.utils._do_push", doc_name=doc.name)
def _do_push(doc_name):
doc = frappe.get_doc("Sales Invoice", doc_name)
call_external_api(doc)
# frappe.db.commit() here works because we're outside the document hook
A related change: frappe.sendmail(..., now=True) used to commit implicitly on v15 and does not on v16.
Which database calls stopped returning strings on v16?
Before v16, frappe.db.get_value("Settings", "Settings", "enabled") returned "1", a string, because Single DocTypes are stored as strings. Plenty of code compared it as a string:
# v15: True — this worked
if frappe.db.get_value("Settings", "Settings", "enabled") == "1":
do_the_thing()
# v16: False — the value is now the integer 1
if frappe.db.get_value("Settings", "Settings", "enabled") == 1:
do_the_thing()
The change hits db.get_value() reads of check and number fields on Single DocTypes (settings). Grep your app for the four suspects, == "1", == "0", != "1", != "0", and audit each one.
A second, subtler change in the same area: the value cache moved from a flat tuple-keyed dictionary to a nested one. If your app called frappe.db.value_cache.pop(("User", "Guest", "full_name"), None) to invalidate a cache entry, that call now does nothing on v16. The new form is frappe.db.value_cache["User"]["Guest"].pop("full_name", None).
What did v16 sort order change to, and what breaks?
Every frappe.get_all(), frappe.get_list(), frappe.db.get_value(), frappe.db.get_values() and frappe.qb.get_query() without an explicit order_by now sorts by creation desc instead of modified desc. If your code relied on the old order (for example, "the most recently touched invoice for this customer"), it now gets the most recently created one, and the business logic is quietly wrong.
Two clean fixes, depending on intent:
# If you always wanted the most recently touched record, be explicit
frappe.get_all("Sales Invoice", filters={"customer": customer}, order_by="modified desc", limit=1)
# If you wanted the most recently created (the new default), no change
frappe.get_all("Sales Invoice", filters={"customer": customer}, limit=1)
Grep for frappe.get_all(, frappe.get_list(, frappe.db.get_value( and frappe.qb.get_query( and add an explicit order_by wherever the caller cares. The migration notes give Frappe's reasons: creation suits most business documents, keeps lists stable while records change, and never needs index updates. Sound reasons, but still a behaviour change.
Which functions were removed outright?
10 rows · click a column to sort
| Replacement | |
|---|---|
frappe.get_lang_dict() | Use per-user language APIs (see wiki) |
frappe.translate.get_dict() | Removed with no direct replacement — audit callers |
frappe.translate.get_lang_js() | Removed |
frappe.translate.get_dict_from_hooks() | Removed |
frappe.flags.in_test (deprecated, removal planned) | frappe.in_test |
frappe.permission.has_permission(..., raise_exception=...) | Same call, replace raise_exception with print_logs |
frappe.geo.country_info.get_translated_dict() (deprecated) | get_translated_countries() |
make_bank_account whitelisted method | frappe.new_doc("Bank Account") in your own code |
make_pricing_rule whitelisted method | frappe.new_doc("Pricing Rule") in your own code |
bleach (no longer a Frappe dependency) | Frappe uses nh3.clean, which strips forbidden tags rather than encoding them; declare bleach yourself if you use it |
The ERPNext-side changes are in the Migration Guide to ERPNext Version 16. Four modules also moved out of Frappe into their own repositories in v16; if your custom app imports from any of them, install the new app:
- Energy Points →
frappe/eps - Newsletter →
frappe/newsletter - Backup Integrations →
frappe/offsite_backups - Blog →
frappe/blog
bench get-app <the-new-app> and bench --site your-site install-app <the-new-app> restore them.
What is the pre-flight before you touch the bench?
Frappe lists its breaking changes by version. The ERPNext upgrade impact preview sorts them by what you have built, a custom app included, and gives the source for each.
0 of 8 steps done
Tick a step’s number when it is done; the ticks stay on this device.
Verify v15 is clean
bench --site your-site.local migrate should complete without an error, and bench doctor should show a healthy scheduler and workers. Fix anything red on v15 before you continue. Upgrading a broken bench is how a two-hour job becomes a two-day one.
Take a full backup of every site on the bench
bench --site your-site.local backup --with-files, then copy the sql.gz and the files tarballs off the server. The v16 upgrade changes the schema; a rollback without a pre-upgrade backup means data loss.
Confirm Python 3.14+ and Node 24+ are installed
python3.14 --version and node --version. Install both from a source that stays current (deadsnakes for Python, NodeSource for Node on Debian/Ubuntu).
Rebuild the bench virtualenv on the new Python
bench setup env --python /usr/bin/python3.14. This recreates the bench's virtualenv against Python 3.14 and reinstalls dependencies. bench pip list should show the versions consistent with Frappe v16's pyproject.toml.
Grep your custom app for the six known-break patterns
Before any upgrade command: search for def has_permission, frappe.db.commit( inside hooks.py-referenced modules, == "1" / == "0" on db.get_value returns, frappe.flags.in_test, raise_exception= in permission calls, and imports from Newsletter/Blog/Energy Points/Backup Integrations. Fix each in the branch, then commit before you switch the bench to v16.
Switch and rebuild
bench switch-to-branch version-16 frappe erpnext --upgrade, then bench setup requirements, then bench build. An error at this stage is a version or dependency problem; read the message before you search for it.
Migrate the sites
bench --site your-site.local migrate. This applies the schema changes and runs patches. Watch the log: patches print progress, and a failing patch names itself.
Reinstall your custom app if it drifted
bench --site your-site.local install-app your_custom_app. If it errors here after all the above, the error names the API or import that failed; go to the matching section above, fix it in your app's code, then repeat.
What is the fix order after a broken upgrade?
If you skipped the pre-flight and the bench is now half-upgraded, do these in order:
- Confirm the branches.
bench versionshould listfrappe 16.xanderpnext 16.x. If one is on 15 and the other on 16, fix that first: get both on 16. - Reinstall the Python and JavaScript dependencies.
bench setup requirementsinstalls what the v16 apps declare; a half-finished upgrade often leaves v15 packages behind. - Rebuild the assets.
bench build --forcerebuilds instead of reusing assets a mid-flight upgrade left behind. If the build fails, it is almost always the Node version; see the check above. bench --site your-site.local migrate. Applies the schema and runs the patches. If it fails with a traceback in your app, a hook is failing under the new API, and the traceback names it.bench --site your-site.local install-app your_custom_app --force. If the failed upgrade left your app half-installed,--forcereinstalls it over the partial state.
What else looks like "custom app not building"?
Three problems that look like build or install failures but are infrastructure issues:
- Assets 404 after
bench build: a static-file misconfiguration in split-containerfrappe_dockerdeployments, unrelated to your app. See the frappe_docker asset break guide. - Background jobs stopped after the upgrade: usually the scheduler left paused mid-upgrade, not code. See ERPNext v16 background jobs not running.
bench install-appsucceeds but the app is not visible: runbench --site your-site list-appsto see what the site has installed, and checksites/apps.txtlists the app for the bench. Thenbench build --app your_custom_appand clear the cache.
FAQ
Why does bench install-app fail on v16 but worked on v15?
Usually a Python or Node version mismatch. v16 needs Python 3.14 and Node 24+; v15 ran on Python 3.10+ and Node 18+. If the traceback points into frappe rather than your app, check the versions first: python3 --version and node --version.
How do I know if my has_permission hook is silently denying access?
Two ways. Fast check, on staging only: temporarily add return True at the top of each custom has_permission and see if the access problem goes away; if it does, a fall-through path was returning None. Thorough check: grep for def has_permission across your app and confirm every function returns True or False explicitly on every branch.
Do I need to rewrite my custom app for v16?
No. The v16 changes are targeted: you fix the patterns listed in this post, not the app's architecture. A custom app of a few DocTypes and hooks needs small edits, not a rewrite. If someone quotes you a rewrite, get a second opinion.
Is v16 stable enough to run in production yet?
Version 16 has been in stable release since 12 January 2026, with regular point releases since (v16.50.0 on 6 October 2026). Whether it suits a given site depends on the apps installed and how customised it is. If in doubt, run v16 on a copy of the site alongside v15 for a few weeks before switching.
Comments & ratings
No comments yet. Start a new discussion.
Manoj · Published on 9 August 2026
Worked with us? Leave a Google review