agent edited a migration file after it was already applied - now every fresh environment fails checksum validation

TL;DR

Never edit an applied migration. Write a new corrective migration instead. To unblock fresh environments, either restore the file to its applied content and put your edits in a new file, or use the tool's repair command to align the history table with the edited file. Checksums exist precisely to catch this: the file on disk no longer matches the hash recorded when it ran.

agent edited a migration file after it was already applied - now every fresh environment fails checksum validation

Steps

1. Find the mismatch. Flyway flyway info names the version that fails validation; Prisma reports the failed checksum on migrate; for Alembic/Django compare the file against version control with git log on the migrations directory. Expected: you know exactly which file changed after being applied.

2. Decide which side is the truth. If the edited content never reached production (only local or dev databases ran it), the applied file wins: restore the original file from version control and put your edits in a brand new migration file. Expected: git diff on the old migration file is empty.

3. If production already ran the edited content, the file must match production. Update the file to the applied content, then align the history: Flyway flyway repair rewrites the stored checksum; Prisma prisma migrate resolve --applied "[name]" marks it applied as-is. Expected: flyway validate (or the Prisma equivalent) passes with no checksum error.

4. Verify on a truly fresh database: wipe a dev database and run the full migration chain from zero. Expected: every migration applies cleanly and validation passes.

5. Lock the workflow so it cannot happen again. Add a CI check that fails if an already-merged migration file changed, for example a job that diffs the migrations directory against the main branch. Expected: the check is green now and would catch the next edit.

Use this when

• Checksum or validation errors appear on fresh environments.
• A migration file was modified after being applied somewhere.
• The history table's stored hash differs from the file on disk.
• An agent "fixed" a migration by editing it in place.

Not for this skill when

• Checksum failures come from tool version skew between environments (different problem).
• A migration failed without being edited (that is a failed migration, not a checksum mismatch).
• The drift is between the database and the models, not the migration files.

Variant phrasings

• flyway checksum mismatch after editing migration
• do not edit applied migrations
• prisma checksum error on edited migration file
• validation failed migration file was modified

Why it happens

Migration tools fingerprint each file and store the fingerprint in the history table when the migration runs. Editing the file later makes the stored fingerprint stale, so validation fails everywhere the file gets re-applied. The check is doing its job: it is telling you the file that ran in production is not the file you are about to run.

Edge cases

• If the edit reached prod AND dev databases ran the original, the environments disagree with each other. Repair each environment's history row to match what actually ran there.
• Never repair away a genuinely failed history row without checking what ran. Repair is for checksum mismatches, not for hiding failures.
• Keep the old migration files until every environment has migrated past a squash or replacement. Deleting them early recreates this exact problem.

Provenance

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