flyway error: Detected applied migration not resolved locally - how to repair

TL;DR

The database history lists migrations that have no corresponding file on disk, usually because someone deleted the file or switched branches. List the orphaned versions from flywayschemahistory, restore the missing files from version control when the migrations are real, and only remove history rows when you are certain the deletion was deliberate and universal. Validate after every change.

The query

flyway error: Detected applied migration not resolved locally - how to repair

Use this when

• flyway fails with "Detected applied migration not resolved locally"
• Migration files were deleted or the branch changed under the agent
• flywayschemahistory has versions with no local file
• Fresh checkouts cannot validate against an existing database

Not for

• Checksum mismatches on files that exist (use repair, not restoration)
• Migrations that failed to apply (those are failed rows, a different repair path)
• A brand-new database with no history at all (just migrate)

Steps

1. List the orphaned versions

SELECT version, description, success FROM flyway_schema_history ORDER BY installed_rank;

Compare against the files in the migrations directory. Every history version with no matching file is orphaned.

Expected output: a concrete list of versions present in history but missing on disk, e.g. V12 with no V12__ file.

2. Check version control for the missing files

git log --diff-filter=D --name-only -- [migrations dir]/ | head -50

Expected output: the deleted file names and the commits that deleted them. If the files exist in git history, restoration is the safe path.

3. Case A: the migrations are real - restore the files

git checkout [commit before deletion] -- [migrations dir]/V12__[name].sql

Do this for every orphaned version. The files must byte-match what was applied, or the next validate will raise checksum mismatches instead.

Expected output: every history version resolves to a local file again. Run flyway validate to confirm.

4. Case B: the deletion was deliberate and the migration never mattered - clean the history

Only when the orphaned migration never applied successfully anywhere that matters (success = false rows, or dev-only experiments): remove the row by hand or run flyway repair, which clears failed entries and reconciles the history. Never delete success-true rows for migrations that ran in production.

Expected output: the history no longer references unresolvable versions, and validate passes. Document why the row was removed.

5. Prevent recurrence: forbid deleting applied migrations

Add a CI check that every version in a reference history (or simply every file ever committed to the migrations directory) still exists. Deletion of an applied migration becomes a build failure, not a deploy-time mystery.

Expected output: the next deletion attempt fails loudly at pull-request time.

Tool compatibility

flyway 9.x and 10.x. The "not resolved locally" detection and repair behavior are consistent across these versions.

Variant phrasings

flyway Detected applied migration not resolved locally how to repair

Steps 1 through 3: list orphans, restore from git, validate. Restoration beats history surgery in nearly every real case.

flyway migration file deleted but applied

Steps 3 and 4: restore if it ran anywhere real; only clean history for never-applied experiments.

flywayschemahistory has versions with no files

Step 1 gives you the exact list; step 2 tells you whether git can give the files back.

Why it happens

Flyway validates by joining two sets: migrations resolved from the filesystem and migrations recorded in the history table. A version recorded as applied but absent from disk is unresolvable, and flyway refuses to proceed because it cannot know what that version did. The error protects you from a history that no longer describes reality.

Edge cases

• Restored files must byte-match the applied content or you trade this error for checksum mismatches: restore from the commit that was current when the migration ran, not from a later edited copy.
• Branch switching is the common cause: the agent checked out a branch whose migrations directory lacks versions the database already applied. Restore the branch or the files before migrating.
• repair removes failed entries but does not resurrect deleted files for success-true rows: do not expect repair alone to fix genuinely missing files.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst4izfgl9At6oyYqF4gR1LQ