Atlas "migrate lint" / "checksum mismatch" Failures in CI

By Kaveh Alemi·Latchkey

Atlas keeps an integrity file (atlas.sum) over the migration directory and lints new migrations for unsafe changes. CI fails either because a migration file changed without re-hashing, or because lint flagged a destructive/blocking change. Both are deterministic.

What this error means

atlas migrate lint or a CI check fails with a checksum mismatch against atlas.sum, or with lint diagnostics about a destructive/irreversible change. The same files fail the same way every run.

Error: checksum mismatch: migration file 20240115_add_orders.sql was
modified after atlas.sum was generated. Run 'atlas migrate hash'.
# or
Error: destructive change detected: dropping column "legacy_code"

Common causes

Migration edited without re-hashing

A migration file in the directory was changed after atlas.sum was generated, so the integrity hash no longer matches.

Lint flagged a destructive or unsafe change

migrate lint detects drops, irreversible changes, or operations unsafe for online migration and fails the gate.

How to fix it

Re-hash after editing migrations

Regenerate the integrity file so it matches the current migration directory, and commit it.

atlas migrate hash
git add migrations/atlas.sum

Address lint findings deliberately

1. Read the lint diagnostic - it names the unsafe change and why.
2. Stage destructive changes (deprecate, backfill, then drop) or acknowledge them per your policy.
3. Run atlas migrate lint --latest 1 locally to reproduce the CI finding before pushing.

How to prevent it

• Generate migrations with atlas migrate diff so atlas.sum stays current.
• Run atlas migrate lint in CI to catch unsafe changes early.
• Treat existing migration files as immutable; add new ones for changes.

Frequently asked questions

Related guides

References

• GitHub Actions documentation