Troubleshooting Motoko Migrations

Reference for the failure modes of the mops-managed migration chain (migrations/).

Do not load this for routine work. Writing a migration, deciding implicit vs explicit, or naming a new file is covered by migrating-motoko-actors — that skill's rules are sufficient for the normal path. Come here when:

• a compatibility or migration diagnostic does not match what you see in main.mo
• a write to a migration file fails, or you are tempted to rename/delete one
• the first file in the chain has a non-empty OldActor and you are unsure whether that is a bug
• the task asks you to remove migrations, restore inline initializers, or go back to (with migration = ...)
• mops check complains about a state shape that is not in the current source

How the runtime decides what to run

• The whole chain is compiled into the backend wasm. There are no separate migration artifacts — changing any migration file changes the wasm.
• Applied migrations are tracked by module name (the filename without .mo) in the canister's persistent metadata.
• On upgrade, the runtime replays only the migrations that module name says have not been applied yet. Deploying onto a canister several versions behind replays all the missing steps in one upgrade — you never need intermediate deploys to "catch up".
• On fresh install, every file in the chain replays in lexicographic order. Every migration ever added runs on every fresh install of the project, forever.