How to fix Flyway: Validate failed: Migration checksum mismatch in PostgreSQL

The error message displays the version and both checksums. Find the specific migration file and note the version number.

Flyway: Validate failed: Migration checksum mismatch for migration version 1.1
-> Applied to database: 1234567890
-> Resolved locally: -987654321
Either revert the changes to the migration, or run repair to update the schema history.

The version number (e.g., "1.1") tells you which migration file is mismatched. Check your migrations directory (typically db/migration/) for V1.1__*.sql or similar.

Check if the migration file matches what was originally deployed. Compare the current version with version control history or backups.

# If using Git, check the file history
git log --oneline -- db/migration/V1.1__your_migration.sql

# View the diff between current and last committed version
git diff HEAD -- db/migration/V1.1__your_migration.sql

# Show the file as it was when deployed
git show HEAD:db/migration/V1.1__your_migration.sql

If the file has been modified (intentionally or unintentionally), you have two paths forward:
1. Development: Revert to the original version or use flyway repair
2. Production: Revert changes and create a new migration file

If the modifications were accidental or unnecessary, restore the migration file to its original version:

# Restore from Git
git checkout HEAD -- db/migration/V1.1__your_migration.sql

# Or restore from backup
cp backup/V1.1__your_migration.sql db/migration/V1.1__your_migration.sql

After reverting, the checksum should match again and Flyway will validate successfully. This is the recommended approach for development environments or when changes should not have been made.

In development environments, you can use Flyway's repair command to realign checksums. This updates the flyway_schema_history table to match the current migration files, allowing validation to pass.

# Using Flyway CLI
flyway repair

# Using Maven
mvn flyway:repair

# Using Gradle
gradle flywayRepair

The repair command:
- Updates checksums of already-applied migrations to match current files
- Removes failed migrations from the history table
- Does NOT re-run migrations or modify the database schema

WARNING: Only use repair in development environments! In production, it can cause serious issues by hiding genuine problems with migrations. Instead, always create new migration files to fix issues.

If Flyway repair is not available or you need fine-grained control, manually update the flyway_schema_history table in PostgreSQL:

-- View the current schema history
SELECT version, checksum, success FROM flyway_schema_history ORDER BY version;

-- Update the checksum for the mismatched migration
UPDATE flyway_schema_history
SET checksum = -987654321  -- Use the "Resolved locally" checksum from error
WHERE version = '1.1';

-- Verify the update
SELECT version, checksum, success FROM flyway_schema_history WHERE version = '1.1';

After updating, Flyway should validate successfully. However, manually modifying the schema history table is error-prone and should only be done as a last resort in development environments.

For production databases, never use repair or manual updates. Instead, create a new migration file to correct the database state:

-- db/migration/V1.2__fix_previous_migration.sql
-- Revert the incorrect changes from V1.1
DROP TABLE IF EXISTS incorrect_table;
DROP INDEX IF EXISTS incorrect_index;

-- Apply the correct changes
CREATE TABLE correct_table (
  id SERIAL PRIMARY KEY,
  name VARCHAR(255) NOT NULL
);

Then delete or isolate the problematic V1.1 migration file so it will not be modified again. Create new migrations (V1.2, V1.3, etc.) for future changes. This ensures audit trails and allows rollback to previous versions if needed.

Follow these practices to avoid checksum mismatches:

1. Treat migrations as immutable: Once a migration is applied to any database, never modify it. Create new migrations instead.

# DON'T modify existing V1.1__migration.sql
# Instead, create a new one:
# V1.2__fix_v1.1_issue.sql

2. Use version control: Keep migration files in Git with consistent formatting:

# Ensure consistent line endings (LF, not CRLF)
git config core.safecrlf true
echo "* text eol=lf" >> .gitattributes

3. Document migration changes: Use Git commits to document why migrations were created:

git commit -m "V1.1__create_users_table.sql: Add user management schema"

4. Run Flyway validate in CI/CD: Catch checksum mismatches before deployment:

# GitHub Actions example
- name: Validate migrations
  run: mvn flyway:validate

5. Use consistent Flyway configuration: Ensure all environments use the same Flyway version and configuration to avoid path-based checksum differences.