Flyway: Migration checksum mismatch

Q: Run flyway:repair

When to use: Use this if you intentionally fixed a typo in an old migration script and need the DB to accept the new checksum.. The repair command updates the checksum stored in the flyway_schema_history table to match the current file on disk.

Q: Revert the migration script to its original state

When to use: Use this if you edited an applied script by accident and don't want to alter the database history.. Undo your changes in the SQL file so the checksum matches the database again. Never edit applied migrations.

Q: Create a new migration script

When to use: Use this if you need to change the schema after a migration has already been applied.. Instead of editing V1, create V2. Flyway applies new scripts without touching old ones.

🔴 The Error You're Seeing

Confirm this matches your console output. If it does, you're in the right place.

ERROR LOG

2026-02-14 22:10:30.100 ERROR 8842 --- [           main] o.s.boot.SpringApplication               : Application run failed

org.flywaydb.core.api.FlywayException: Migration checksum mismatch for migration version 1.0.1
-> Applied to database : 1234567890
-> Resolved locally    : 0987654321

⚡ Quick Fix Works 80% of the time

Run the 'flyway repair' command to update the checksums in the database history table.

mvn flyway:repair

🛠️ Solutions (3 Ways to Fix)

Solution 1✓ Most common cause

Run flyway:repair

👉 Use this if you intentionally fixed a typo in an old migration script and need the DB to accept the new checksum.

The repair command updates the checksum stored in the flyway_schema_history table to match the current file on disk.

# Maven
./mvnw flyway:repair

# Gradle
./gradlew flywayRepair

Solution 2

Revert the migration script to its original state

👉 Use this if you edited an applied script by accident and don't want to alter the database history.

Undo your changes in the SQL file so the checksum matches the database again. Never edit applied migrations.

// Git checkout the file
// git checkout src/main/resources/db/migration/V1__Create_Users.sql

Solution 3

Create a new migration script

👉 Use this if you need to change the schema after a migration has already been applied.

Instead of editing V1, create V2. Flyway applies new scripts without touching old ones.

// Create a new file: V2__Add_Column_To_Users.sql
ALTER TABLE users ADD COLUMN status VARCHAR(20);

📋 Version Notes

Spring Boot 2.x

Flyway 7.x is bundled.

Spring Boot 3.x

Flyway 9.x is bundled. Uses updated API and stricter validation.

🧠 Why this Happens

Tap to expand the deep technical explanation

Flyway tracks which SQL scripts have been run by storing a mathematical checksum of the file. If you edit a file that has already been executed, the checksum changes. On startup, Flyway sees the mismatch and crashes to protect your database from inconsistent state.

The HITEC City Parking Spot Analogy:

It is like editing a historical document after it has been signed and sealed. The archivist (Flyway) notices the ink is fresh and refuses to accept it as the original record.

🛡️ How to Prevent This Next Time

Never edit a migration script after it has been applied to any environment. Always create a new V{n} script for changes.