RunbooksMigration stuck

Prisma migration stuck or drifted

Applies to: core

Symptom

pnpm db:migrate:dev hangs for minutes with no output, or fails with one of:

Error: P3009: migrate found failed migrations in the target database
Drift detected: Your database schema is not in sync with your migration history.
The migration `<timestamp>_<name>` is already recorded as applied but is missing from your migrations directory.

Likely cause

The _prisma_migrations table that PrismaPrismaThe TypeScript ORM HiveCFM uses to talk to Postgres. The schema lives at packages/database/schema.prisma. maintains and the folders under packages/database/migration/ have gotten out of sync. Common triggers:

  • A migration errored halfway, leaving its row in failed state.
  • Someone reset the local DB to a snapshot taken before a migration folder was deleted, so the DB “remembers” an applied migration that no longer exists on disk.
  • A branch switch pulled in migrations that land ahead of your last applied one, and your DB has diverged (the classic “drift”).

HiveCFM also ships data migrations alongside schema migrations, tracked in a separate DataMigration table (see hivecfm-core/packages/database/README.md). They are applied by the same apply-migrations.js script the db:migrate:dev flow runs.

Fix

Inspect migration status

cd /home/ubuntu/AG-DEV/hivecfm-core
pnpm --filter @hivecfm/database exec prisma migrate status

This prints which migrations are applied, pending, or failed. Read the output — the right next step depends on it.

Resolve a single failed or orphaned migration

If the output names a migration stuck in failed, mark it resolved (either as rolled back or applied, based on reality):

# You rolled back the partial changes manually → tell Prisma
pnpm --filter @hivecfm/database exec prisma migrate resolve \
  --rolled-back "<timestamp>_<name>"
 
# The migration actually applied but Prisma thinks it failed
pnpm --filter @hivecfm/database exec prisma migrate resolve \
  --applied "<timestamp>_<name>"

Re-run the normal dev migration path

pnpm --filter @hivecfm/database db:migrate:dev

This runs prisma generate and apply-migrations.js — it will pick up where resolve left off.

Last resort — reset the local database

⚠️

prisma migrate reset drops every table in the target database and reapplies migrations from scratch. All local data is lost. Never run this against a shared or production database. Confirm DATABASE_URL in .env.local points at localhost:5433 before proceeding.

pnpm --filter @hivecfm/database exec prisma migrate reset
# Then re-apply HiveCFM's custom migrations + seed:
pnpm --filter @hivecfm/database db:setup

Verify

pnpm --filter @hivecfm/database exec prisma migrate status
# "Database schema is up to date!"
pnpm --filter @hivecfm/web dev
# Boots without Prisma warnings

Prevent

  • After switching branches, run pnpm --filter @hivecfm/database db:migrate:dev before starting the app. It also regenerates the Prisma client.
  • Do not edit files inside already-applied migration folders — create a new migration instead.
  • Keep local snapshot/restore workflows consistent with the migration folder on disk. If you restore an older dump, either also checkout the matching migration folder or be prepared to migrate resolve.
  • Read hivecfm-core/packages/database/README.md once end-to-end — the two-table (schema vs. data) migration model is not standard Prisma.
Hub 401Docker volumes