Fix Flyway Migration Error – Migration Failed During Execution

In this tutorial, you'll learn about Fix Flyway Migration Error. We cover key concepts, practical examples, and best practices.

You run flyway migrate and get "Migration V2__add_users.sql failed" — or "Validate failed: Detected resolved migration not applied". The SQL script looks correct, but Flyway refuses to run it.

Wrong ❌

-- V2__add_users.sql
INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com');

flyway migrate

Error:

ERROR: Migration V2__add_users.sql failed
------------------------------------------
SQL State  : 42P01
Error Code : 0
Message    : ERROR: relation "users" does not exist

The users table hasn't been created yet! It's created in V1__create_users.sql, which was applied successfully. But V2 references a column that doesn't exist — because V1 has a different schema, or V2 was supposed to run after V1 but there's a gap.

Right ✅

-- V1__create_users_table.sql
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    email VARCHAR(255) NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);

-- V2__add_sample_user.sql
INSERT INTO users (name, email) VALUES ('Alice', 'alice@example.com');

flyway migrate

Successfully applied 2 migrations (execution time 00:00.123s)

Fix checksum mismatch:

If you edited a migration that was already applied:

flyway validate
# → Validate failed: Migration V2__add_users.sql checksum mismatch

Don't edit applied migrations. Instead, create a new migration:

-- V3__fix_users_data.sql
UPDATE users SET name = 'Alice Smith' WHERE email = 'alice@example.com';

If you must repair (development only):

flyway repair
# Updates the checksum in the flyway_schema_history table

Baseline an existing database:

flyway baseline -baselineVersion=3
# Marks all migrations ≤ V3 as already applied

Undo a failed migration (no undo support in community edition):

# Manually revert the changes, then:
flyway repair

Root Cause

Flyway validates migration scripts by checksum before running them. Any edit to an already‑applied migration causes a checksum mismatch. Migration version ordering errors (missing versions, duplicate versions) also cause failures.

Prevention

• Never edit a migration script that has been applied to any environment.
• Use flyway validate in CI to catch checksum mismatches early.
• Use flyway info to see the current state before running migrate.
• Name migrations with consecutive versions: V1__, V2__, V3__ — no gaps.

Common Mistakes with migration error

1. Mixing let bindings with <- bindings in do notation, producing type errors
2. Overlapping type class instances that cause GHC to reject the program with ambiguous dispatch errors
3. Non-exhaustive pattern matches that compile with warnings then crash at runtime

These mistakes appear frequently in real-world FLYWAY code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ

Flyway migrations are covered in the DodaTech Database Migrations course.