flyway error: Validate failed - Migration checksum mismatch for migration version 12

TL;DR

Someone edited migration V12 after it was applied, so the file's checksum no longer matches the one flyway recorded. If the edit already ran everywhere and is intentional, run flyway repair to update the recorded checksum. If the edit was accidental or has not run everywhere, restore the original file from version control instead. Then run flyway validate to confirm the chain is clean.

The query

flyway error: Validate failed - Migration checksum mismatch for migration version 12

Use this when

• flyway validate fails with "Migration checksum mismatch"
• A migration file was edited after it was applied
• Deploys fail validation on a version that used to pass
• An agent "fixed" a migration file in place instead of writing a new one

Not for

• Migrations that failed before applying (check the success flag, use repair differently)
• "Detected applied migration not resolved locally" (the file is missing, not edited)
• Checksum mismatches on migrations that never applied anywhere (just fix the file)

Steps

1. Confirm which version mismatches and how it applied

flyway validate

Then check the recorded state:

SELECT version, description, checksum, success FROM flyway_schema_history WHERE version = '12';

Expected output: validate names version 12, and the history row shows success = true with a checksum that differs from the current file. Success-true plus mismatch means "edited after applying".

2. Diff the current file against the applied original

git log --oneline -- [migrations dir]/V12__[name].sql
git diff [commit when applied] HEAD -- [migrations dir]/V12__[name].sql

Expected output: the exact edit that changed the checksum. Classify it: cosmetic (whitespace, comments) or semantic (different DDL). This classification picks the fix.

3. Case A: the edit is intentional and already applied everywhere - repair

flyway repair

Expected output: repair updates the recorded checksum for version 12 to match the edited file. It does not re-run the migration. Follow with flyway validate to confirm clean. Only choose this when every environment already ran the edited content.

4. Case B: the edit was a mistake or has not run everywhere - restore the file

git checkout [commit when applied] -- [migrations dir]/V12__[name].sql

Expected output: the file matches the recorded checksum again and validate passes with no repair needed. Put the intended change in a NEW migration (V13) instead of editing history.

5. Verify and lock the process

flyway validate

Expected output: "Successfully validated" with no mismatches. Then add a CI rule: applied migration files are immutable; any diff to an already-applied file fails the build.

Tool compatibility

flyway 9.x and 10.x (repair and validate behave the same for this case). Applies to all supported databases.

Variant phrasings

flyway Validate failed Migration checksum mismatch

Steps 1 through 3: confirm it applied successfully first, then repair only if the edit is intentional and universal.

flyway checksum mismatch how to fix

Step 2 decides everything: cosmetic or intentional-everywhere means repair; anything else means restore the file and write a new migration.

flyway repair checksum mismatch

Step 3: repair updates the recorded checksum without re-running. It is the right tool exactly when the edited content already ran everywhere.

Why it happens

Flyway checksums every migration file and stores the checksum at apply time. Validate recomputes checksums and compares; a mismatch means the file changed after the database recorded it. Flyway treats this as an error because silently divergent histories are how environments drift apart beyond repair.

Edge cases

• repair on a file whose edit never ran in production makes prod and dev disagree about what V12 did: restore the file instead.
• Line-ending changes (CRLF vs LF) alone change the checksum: normalize line endings in the repo rather than repairing repeatedly.
• If several versions mismatch, fix them one at a time and re-validate between each; a bulk repair can hide a genuinely wrong edit.
• Agents: never edit an applied migration file to "fix" it. New problem, new migration version.

Provenance

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