migration agent stuck in a retry loop: flyway fails, repairs, re-applies, and fails again on the same checksum every...

TL;DR: Stop running repair - it is not the fix here. A repeating checksum failure means the migration file on disk no longer matches the file that was originally applied, and repair cannot reconcile that. Find the mismatched version with flyway info, then either restore the original file content or align the history deliberately. Only then run migrate.

migration agent stuck in a retry loop: flyway fails, repairs, re-applies, and fails again on the same checksum every time

1. Break the loop first: stop the agent's retry cycle so it is not hammering the database.

Expected: no new flyway processes are running.

1. Find the mismatched version: run flyway info and look for the version flagged with a checksum mismatch.

Expected: one version row shows as applied in the history table but its file checksum differs.

1. Compare the file on disk against what was applied: check version-control history for that migration file.

Expected: you find the edit - someone (or an earlier agent pass) modified the SQL after it was applied.

1. Fix the mismatch one of two ways: restore the file to its originally-applied content (keeps history truthful), or if the applied change must stay, update the history deliberately with a documented repair.

Expected: flyway info no longer reports a checksum mismatch for that version.

1. Run flyway migrate once, observed.

Expected: it applies only genuinely pending migrations and reports success - no checksum error.

Use this when

• flyway repair runs clean but migrate fails on the same checksum right after
• an agent is looping fail, repair, re-apply with no progress
• the same version number appears in every failure

Not for this skill when

• the migration fails with a SQL syntax or data error - fix the SQL
• the file was legitimately meant to change - then the question is how to handle it, not a loop
• no migration has ever applied successfully - check connectivity and configuration first

Variant phrasings

• flyway checksum mismatch keeps coming back after repair
• flyway validate fails on the same version every time
• flyway repair does not fix the checksum error

Why it happens

Flyway records a checksum of each migration file when it applies it, and validate compares the files on disk against the history table on every run. repair only fixes bookkeeping problems (failed rows, missing history entries) - it does not and cannot make a changed file match its recorded checksum. So the loop is: migrate fails validation, repair "fixes" nothing about the file, migrate fails validation again. The agent keeps polishing the symptom while the edited file sits there unchanged.

Edge cases

• If the file was edited because the applied migration was wrong, the correct fix is a NEW migration that corrects the schema, not editing history - keep the audit trail truthful.
• Multiple environments with different file contents for the same version means the mismatch follows you - fix it in version control, not per database.
• Disabling validation to escape the loop hides real drift - only do it temporarily and deliberately, never as the agent's default.
• An agent that edits migration files as part of its workflow will recreate this loop - make applied migrations read-only to the agent.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_YQAXqBsW9nP3tF21jmvZkQ