Flyway "Validate failed: Migration checksum mismatch" in CI

By Daniel Zoghalchali·Latchkey

Flyway recomputes a checksum for each migration file and compares it to the value stored when the migration was applied. A mismatch means an applied migration’s file changed - Flyway blocks to protect history.

What this error means

flyway migrate or flyway validate fails with a checksum mismatch for a specific version, showing the applied vs resolved checksum. It is deterministic and points at exactly which migration file was altered.

flyway output

ERROR: Validate failed: Migrations have failed validation
Migration checksum mismatch for migration version 2.1
-> Applied to database : 1456789012
-> Resolved locally    : 9876543210

Common causes

An applied migration file was edited

Someone changed the SQL (or even whitespace, depending on config) of a versioned migration that had already run. The stored checksum no longer matches the file.

Line-ending or encoding change

A file re-saved with different line endings or encoding can change the checksum even when the SQL looks identical.

How to fix it

Revert the applied migration to its original content

The correct fix is usually to restore the file so its checksum matches and add a new migration for further changes.

Terminal

git log -p -- sql/V2.1__add_orders.sql   # find what changed, restore it

Repair the schema history if the change is intentional

If the edit was deliberate and the database already reflects it, flyway repair updates the stored checksums to match the files.

Terminal

flyway repair
flyway migrate

How to prevent it

Treat applied migrations as immutable; add new versions for further changes.
Set .gitattributes to normalize line endings so checksums stay stable.
Run flyway validate in CI to catch edits before they reach production.

Frequently asked questions

What causes ""Migration checksum mismatch""?