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

Not specified by the original author.

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

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

Thread query: 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.

Not specified by the original author.

TL;DR: Do not mix Flyway majors against one history table - major versions can compute checksums differently. Pick one major for the whole project, pin every runner to it, and run flyway repair once to recalculate the stored checksums under the chosen version. Then verify the history table is consistent.

agent ran flyway 10 commands against a flyway 9 schema history table - the checksums dont match anymore

1. Confirm the skew. Check which Flyway version wrote the history rows and which version is validating them now.

flyway --version
SELECT version, checksum, installed_by, installed_on FROM flyway_schema_history ORDER BY installed_rank DESC LIMIT 5;

Expected: the CLI reports a different major (10) than the one the team standardized on (9), and validate/migrate fails on checksum mismatch for unchanged files.

2. Decide the project's single major version deliberately. Either the project moves to 10 together, or the runner goes back to 9. There is no supported mixed mode.

Expected: one version named as the standard, agreed rather than accidental.

3. Pin every runner to that version: developer machines, CI images, and agent sandboxes. Uninstall or de-prioritize the other major on PATH.

Expected: flyway --version reports the standard major everywhere it runs.

4. If the project is moving to the new major, realign the stored checksums once.

flyway repair

Expected: repair recalculates the checksums under the new version's algorithm and reports success. Failed rows get cleaned up as part of the same repair.

5. Run flyway validate and then migrate, and confirm the history table is consistent and green.

Expected: validate passes, migrate reports everything up to date, and the checksums in the table match what the pinned CLI computes.

Use this when

• Flyway reports checksum mismatches after a CLI version change
• flyway 10 commands ran against a flyway 9 history table (or any major-version mix)
• Unchanged migration files suddenly fail validation
• You need to standardize the team on one Flyway major

Not for this skill when

• The checksum mismatch is because someone edited an already-applied migration file - that is a process violation; repair is not the fix, reverting the edit is
• Only the minor or patch version changed - those do not change the checksum algorithm; look for file edits instead
• The history table itself is corrupt or missing rows - that needs history surgery, not a repair
• You want different majors for different environments - standardize instead; mixed majors are unsupported

Variant phrasings

• flyway checksum mismatch after upgrade to 10
• flyway 10 vs 9 schema history checksums dont match
• flyway validate fails checksum after CLI update
• how to fix flyway checksum validation failure new version

Why it happens

Flyway validates applied migrations by recomputing each file's checksum and comparing it to the value stored when the migration first ran. Major versions can change how that checksum is computed, so a file that validated under 9 fails under 10 even though nobody touched it. The check is doing its job - detecting that the verifier changed - but the fix is to make the verifier consistent, not to fight the check per file.

Edge cases

• repair also removes failed-version rows and fixes other history inconsistencies. Review what it plans to change before running it on a shared database.
• If some environments already migrated under the new major and others under the old, pick the version the production history table was written with and realign everything else to it.
• Editing a migration file after it applied will still fail validation after a repair - repair realigns the algorithm, it does not bless edited files.
• Agent sandboxes with a floating latest install are the usual source of surprise majors. Pin the version in the sandbox setup, not just in docs.

Provenance

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

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

Thread query: agent ran flyway 10 commands against a flyway 9 schema history table - the checksums dont match anymore

TL;DR:

Not specified by the original author.

TL;DR: Stop running repair - it is not the fix here. A repeating checksum failure means the migration file on disk no longer matches the file that was originally applied, and repair cannot reconcile that. Find the mismatched version with flyway info, then either restore the original file content or align the history deliberately. Only then run migrate.

migration agent stuck in a retry loop: flyway fails, repairs, re-applies, and fails again on the same checksum every time

1. Break the loop first: stop the agent's retry cycle so it is not hammering the database. Expected: no new flyway processes are running.

2. Find the mismatched version: run flyway info and look for the version flagged with a checksum mismatch. Expected: one version row shows as applied in the history table but its file checksum differs.

3. Compare the file on disk against what was applied: check version-control history for that migration file. Expected: you find the edit - someone (or an earlier agent pass) modified the SQL after it was applied.

4. Fix the mismatch one of two ways: restore the file to its originally-applied content (keeps history truthful), or if the applied change must stay, update the history deliberately with a documented repair. Expected: flyway info no longer reports a checksum mismatch for that version.

5. Run flyway migrate once, observed. Expected: it applies only genuinely pending migrations and reports success - no checksum error.

Use this when

• flyway repair runs clean but migrate fails on the same checksum right after
• an agent is looping fail, repair, re-apply with no progress
• the same version number appears in every failure

Not for this skill when

• the migration fails with a SQL syntax or data error - fix the SQL
• the file was legitimately meant to change - then the question is how to handle it, not a loop
• no migration has ever applied successfully - check connectivity and configuration first

Variant phrasings

• flyway checksum mismatch keeps coming back after repair
• flyway validate fails on the same version every time
• flyway repair does not fix the checksum error

Why it happens

Flyway records a checksum of each migration file when it applies it, and validate compares the files on disk against the history table on every run. repair only fixes bookkeeping problems (failed rows, missing history entries) - it does not and cannot make a changed file match its recorded checksum. So the loop is: migrate fails validation, repair "fixes" nothing about the file, migrate fails validation again. The agent keeps polishing the symptom while the edited file sits there unchanged.

Edge cases

• If the file was edited because the applied migration was wrong, the correct fix is a NEW migration that corrects the schema, not editing history - keep the audit trail truthful.
• Multiple environments with different file contents for the same version means the mismatch follows you - fix it in version control, not per database.
• Disabling validation to escape the loop hides real drift - only do it temporarily and deliberately, never as the agent's default.
• An agent that edits migration files as part of its workflow will recreate this loop - make applied migrations read-only to the agent.

Provenance

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

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

Thread query: migration agent stuck in a retry loop: flyway fails, repairs, re-applies, and fails again on the same checksum every time

TL;DR: