Save, submit and cancel are not three methods. They are one method, save(), called with a different docstatus: 0 stays 0, 0 becomes 1, 1 becomes 2. The hooks you know are steps inside it.
Pick an action below and step through what runs, in order. Switch on the things you have set up, and throw an error at any step to see what is left behind.
Try it
Step through a document’s save
Pick an action, step through what runs, and throw an error to see what is left behind.
Action
Needs: Write and Submit. docstatus goes 0 → 1: the same save, with the submit hooks.
Show what you have set up
At each hook Frappe runs the controller’s own method first, then these, in this order: doc_events, Notification, Webhook, Server Script, Automation.
Throw an error at
Write permissionNext
Timestamp check; docstatus 0 → 1 makes the action “submit”
Submit permission
Values you may not write at permission level 1+ are reset
Linked documents exist and none is cancelled
before_validatedoc_events handlers
validatedoc_events handlers
before_submitdoc_events handlers
Mandatory fields, selects, lengths and any workflow rule
Runs after validate, so validate can still fill a required field.
Row updated with docstatus = 1
on_updateFires on submit too, before on_submit.doc_events handlers
on_submitdoc_events handlers
Cache cleared, realtime update sent, search index and version saved
on_changeRuns last, after the version is saved.doc_events handlers
Frappe v16.52.0. The same order holds on v15.123.0, except: no Automations, no discard, and doc_events handlers may commit.
What runs on Save?
First the permission check: Write for an existing document, Create for a new one. Then Frappe compares the modified timestamp, so a save made from an out-of-date copy is refused. It resets values in fields the user may not write, checks that every link exists, and runs before_validate, validate and before_save. Only then does it check mandatory fields, which is why validate can still fill a required field. After that it writes the row, runs on_update, clears the cache, saves the version, and runs on_change last. A new document also runs before_insert, picks its name, and runs after_insert before on_update.
What does Submit add?
The same save, plus the Submit permission. After validate it runs before_submit. After the write it runs on_update and then on_submit. So a handler on on_update runs when the document is submitted as well as on every draft save. If the DocType has a Workflow, its transition rule is checked together with the mandatory fields.
What does Cancel skip?
Most of it. Cancel runs before_cancel and on_cancel and nothing else from the save path: no before_validate, no validate, no mandatory check. After on_cancel, Frappe refuses the cancel if an active document still links to this one. An amendment is a new document, named after the cancelled one with -1 added, and it goes through Save and Submit again.
Where does your code go?
For each event Frappe runs, in this order: the method on the DocType's controller, the doc_events handlers for that DocType, the handlers for *, Notification rules, Webhooks, Server Scripts and, on v16, Automations. Handlers from several apps run in the order of the site's installed apps. A Server Script's "Before Save" is the validate hook, and there is no Server Script event for before_save.
What happens when something fails?
A request is one database transaction. If anything raises, Frappe rolls the whole request back, including a row that the save has already written. That is why a frappe.throw in on_submit undoes the submit. Webhooks wait in a list and are sent after the commit, so a failed save sends none, and a document saved twice in one request fires a webhook once, with the last version.
Two limits. Your own code that calls frappe.db.commit() keeps whatever it committed. And a background job you start before the commit may read the old data unless you pass enqueue_after_commit=True.
What changed from v15 to v16?
The order above is the same on v15.123.0: the insert, save, before-save and post-save hooks and the docstatus transitions were compared function by function. v16 adds discard() with before_discard and on_discard, the Automations step, and the handler(doc) form without a method argument. In v16, doc_events handlers also cannot commit.
Where this comes from
Read at Frappe v16.52.0 and ERPNext v16.50.0. “(v15)” marks Frappe v15.123.0 and “(ERPNext v15)” marks ERPNext v15.122.0. Each link opens that file at that tag, on that line.
model/document.py:556–560 · model/document.py:1330–1357 · model/document.py:439–528 · model/document.py:560–619 · model/document.py:1090–1159 · model/document.py:595–598 · model/document.py:829–841 · model/document.py:1394–1424 · model/document.py:597–601 · model/document.py:1448–1480 · model/document.py:1247–1269 · model/document.py:1654–1664 · model/document.py:1274–1328 · webhook/__init__.py:6–14 · webhook/__init__.py:73–110 · server_script/server_script_utils.py:6–31 · server_script/server_script_utils.py:39–43 · frappe/app.py:181–187 · frappe/app.py:458–468 · database/database.py:1196–1215 · model/document.py:1636–1650 · database/database.py:1176–1180 · model/document.py:1357–1363 (v15) · model/document.py:1642–1646 · model/document.py:1361 (v15) · model/document.py:1359–1376 · model/document.py:1267 · automation_engine/dispatch.py:11–49 · model/delete_doc.py:169–196 · model/document.py:1210–1227 · model/document.py:1583–1589 · model/naming.py:549–566 · model/document.py:621–626 · model/document.py:281–348 (v15) · model/document.py:380–437 (v15) · model/document.py:880–910 (v15) · model/document.py:1126–1200 (v15)
Official page: Controllers, read 14 October 2026. Pattern: the same payment booked twice.