Knex "The migration directory is corrupt" in CI

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.

knex output

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.

Terminal

npx knex migrate:latest

Restore or stop deleting recorded migrations

Restore the missing migration file if it was deleted by mistake.
Never rename or remove a migration that any database has already run.
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.