Knex "The migration directory is corrupt" in CI

By Daniel Zoghalchali·Latchkey

Knex compares the filenames recorded in knex_migrations against the files on disk. When a recorded migration is missing from the directory, Knex calls the directory corrupt and refuses to continue.

What this error means

knex migrate:latest fails with "The migration directory is corrupt, the following files are missing:" listing migrations that the database recorded but the checkout does not contain.

migration failed with error: The migration directory is corrupt, the following
files are missing: 20240101_create_users.js

Common causes

A recorded migration file is missing from the checkout

A migration that the database already ran was renamed or deleted, so the file no longer matches the knex_migrations record.

Migrating against a database from another branch

A reused database has records from a branch whose migration files are not present in this checkout.

How to fix it

Run against a clean database in CI

Start from an empty database so knex_migrations only references files present in this checkout.

npx knex migrate:latest

Restore or stop deleting recorded migrations

1. Restore the missing migration file if it was deleted by mistake.
2. Never rename or remove a migration that any database has already run.
3. For disposable databases, recreate the database instead of patching the table.

How to prevent it

• Migrate fresh databases in CI to avoid stale records.
• Treat run migrations as immutable; do not rename or delete them.
• Keep migration filenames consistent across branches.

Frequently asked questions

Related guides

References

• GitHub Actions documentation