Flyway "Validate failed: Migration checksum mismatch" in CI

By Kaveh Alemi·Latchkey

Flyway stores a checksum of each migration in the schema history table. Validate recomputes the checksum of the file on disk; if an applied migration was edited, the checksums differ and Flyway fails validation.

What this error means

flyway migrate or flyway validate fails with "Validate failed: Migrations have failed validation" and "Migration checksum mismatch for migration version X" listing the applied versus resolved checksum.

flyway output

ERROR: Validate failed: Migrations have failed validation
Migration checksum mismatch for migration version 2
-> Applied to database : -160814727
-> Resolved locally    : 1242233889

Common causes

An already-applied migration file was changed

Editing a versioned migration that Flyway has already run changes its checksum, so it no longer matches the value recorded in the history table.

Line-ending or encoding changes altered the checksum

A reformat, CRLF/LF change, or re-encoding of an applied file silently changes its checksum even if the SQL is logically the same.

How to fix it

Add a new migration instead of editing applied ones

Revert the edit to the applied file and put the change in a new versioned migration so history stays immutable.

Terminal

# leave V2 untouched; add the change as a new version
# sql/V3__alter_orders.sql

Repair the history if the change is intentional

flyway repair recomputes and updates the checksums in the history table to match the files. Use it only when you deliberately changed an applied migration.

Terminal

flyway repair

How to prevent it

Treat applied migrations as immutable; never edit them.
Keep consistent line endings to avoid spurious checksum changes.
Run flyway validate in CI so edits to applied files fail fast.

Frequently asked questions

What causes "Flyway "checksum mismatch""?