Repository navigation
Troubleshooting
What to do when a run fails. Every failure has an exit code, and
status and history show the
state of each migration.
Exit code 1. The output shows the exception with its stack trace. With --json, it's the details of the
migrationFailed event, and Hosting logs the exception itself. The state and history keep the one-line error.
-
In a transaction, nothing was saved and the migration is still pending: fix it and run
upagain. -
Outside a transaction, whatever it did before throwing is still there. Its state is
failed, and later runs stop until you resolve it, as for a crash: undo what it did (or make sure it's safe to repeat), fix it, runmark <id> --unapplied, thenupagain.
Exit code 4:
✖ 20261014164027 initial was modified after being applied (applied sha256:8eaa3c91..., current sha256:c6700cfc...).
Create a new migration instead, or run `mark 20261014164027 --applied` to accept the change.
Either revert the edit and write a new migration, or accept it with
mark <id> --applied, which stores the new checksum.
onChecksumMismatch: warn turns this into a warning. Whitespace and
comments don't count as edits. See Safety.
Exit code 1, and every later run stops:
✖ 20261014164029 split-full-name is in state 'applying' from run 6704b0c1 on build-agent-12. Inspect the data,
then run `mark 20261014164029 --applied` or `mark 20261014164029 --unapplied`.
The process died (killed, out of memory, machine lost) while the migration was running, so nobody knows how far it got. Look at the data, then:
-
mark <id> --appliedif it finished; -
mark <id> --unappliedif it should run again, after undoing what it did if it isn't safe to repeat.
The same applies to rollingBack after a down.
Exit code 3:
… Waiting for lock held by run 6704b0c1 (build-agent-07), which expires at 2026-10-14 16:51:12Z.
✖ Timed out after 60s waiting for the migration lock held by run 6704b0c1 (build-agent-07), which expires at 2026-10-14 16:51:12Z.
Another run is in progress: wait for it, or raise lockWaitTimeout. Locks are
renewed while a run is in progress and expire lockTtl seconds after a run dies, so a crashed run's lock clears on its
own.
To remove one sooner, use unlock --force, but only if you're sure its run has
stopped.
Exit code 4 from plan or up, with ✖ blocked next to the change and an error saying why. Nothing was changed.
Each has its own way through:
| Blocked by | See |
|---|---|
indexes.onRebuild: fail |
Rebuilds (--allow-rebuild) |
| No declared index uses a field the existing ones use |
Typed definitions (--allow-unmatched) |
| Converting to capped |
Converting to capped (--allow-convert-to-capped) |
| An option MongoDB can't change |
Changes MongoDB can't make (--skip-unchangeable) |
| Existing documents fail a validator |
Validators (--allow-invalid-documents) |
| A conflict with an ignored index | Undeclared indexes |
| A collection with a view's name | Views |
status shows superseded, and up warns. A newer build replaced this definition recently, so an older build won't
undo it. See rolling deploys. Use --allow-superseded if you're rolling back
on purpose.
Exit code 6. The tool only shows build output when a build fails. MM codes come from the source generator; see
Build Errors.
Exit code 5. Update the tool:
dotnet tool update Kevsoft.MigrateMongo.Tool
See How It Works.
Ctrl+C and SIGTERM cancel the running migration through its CancellationToken, so pass it to every driver call.
The lock is kept until the migration's code returns, even if it ignores the token, and is then released. A transactional
migration is rolled back. One outside a transaction that ran to the end is recorded as applied, so a cancel doesn't
leave a finished migration marked failed.
- Check the variables the config references are set: an unset one is reported before connecting.
- For a bastion, see SSH Tunnels. A failed host key check prints the server's fingerprint.
- For
MONGODB-AWS, see AWS IAM Authentication.
Kevsoft.MigrateMongo ·
NuGet ·
Releases ·
Issues ·
Found a mistake? These pages live in
wiki/ on main; pull requests welcome.
Get started
Migrations
- Writing Migrations
- Transactions
- Recording Results
- Dependency Injection
- Custom Templates
- Adopting an Existing Database
Collections
- Managing Collections
- Indexes
- Search Indexes
- Collection Options
- Validators
- Views
- Undeclared Collections
Deploying
Connecting
Reference
Concepts