By default, Flyway fails migration when it detects a version gap, because it assumes a migration is missing.
📌 One-liner:
“A version gap is treated as a missing migration and causes validation to fail.”
What Flyway considers a “version gap”
Example migrations:
V1__init.sql
V3__add_index.sql
Missing:
V2__something.sql
Flyway expects monotonic version ordering:
- Versions must increase without gaps
- Every version is intentional and traceable
What Flyway actually does
During validation (validateOnMigrate=true by default):
- Flyway scans all available migrations
- Detects missing versions
- Throws an error before executing anything
Typical error:
Validate failed: Detected resolved migration not applied to database: 2
➡️ Migration is aborted
Why Flyway is strict about this
A version gap usually means one of these:
- Someone deleted a migration file
- A migration wasn’t committed
- Two branches were merged incorrectly
- Different environments have diverged histories
Interview phrase:
“Flyway fails fast to prevent silent schema drift.”
How to resolve a version gap (correct ways)
✅ Option 1: Restore the missing migration (BEST)
- Re-add
V2__... - Re-run migrate
✅ Option 2: Baseline or repair (carefully)
If the gap is intentional and historical:
- Use
flyway baseline(one-time) - Or mark missing migration as deleted via
repair
Only if:
- You fully understand the DB state
- The schema already includes the change
❌ Option 3: Disable validation (red flag)
flyway.validateOnMigrate=false
This hides problems and is not acceptable in prod.
outOfOrder — related but NOT the same
Interviewers love this trap.
flyway.outOfOrder=true
Allows:
V1 → V3 → later V2
But:
- It still requires all migrations to exist
- It does not allow gaps
- It allows late execution, not missing files
📌 Key sentence:
“Out-of-order allows late migrations, not missing ones.”
Repeatable migrations don’t count
R__ migrations:
- Have no version
- Don’t participate in gap detection
- Are unaffected by version gaps
Real-world example (production)
“Branch A added V2, Branch B added V3. Branch B got deployed first.”
Outcome:
- Prod has V3 applied
- V2 arrives later
- With
outOfOrder=true→ V2 runs - Without it → Flyway fails
But if V2 never existed at all → gap → failure.
Interview-ready answer (perfect)
2–3 sentences:
“If Flyway detects a version gap, it treats it as a missing migration and fails validation, aborting the migrate operation. This is a safety mechanism to prevent untracked or deleted migrations from causing schema drift. The correct fix is to restore the missing migration or intentionally baseline or repair, not to disable validation.”