• Home
  • Troubleshooting

Troubleshooting

Common issues and solutions for Prisma Migrations

Migration Lock Issues

An owner-scoped row lease prevents concurrent migration runs. Active migrations renew the lease; a crashed process stops renewing it and the lease expires.

Check Lock Status

npx prisma-migrations lock check

Release Stuck Lock

npx prisma-migrations lock release --force

Use lock release only when you’re certain no other migration is running.

Checksum Validation Errors

If you get “migration has been modified” errors, it means an applied migration file was changed after being applied.

Skip Validation (Recovery Only)

const migrations = new Migrations(prisma, {
  skipChecksumValidation: true,
});

Warning: Only use this to recover from checksum issues. Never modify applied migrations in production.

Concurrent Deployment Issues

When deploying multiple instances simultaneously, use upIfNotLocked() to avoid conflicts:

const result = await migrations.upIfNotLocked();

if (result.ran) {
  console.log(`Applied ${result.count} migrations`);
} else {
  console.log(result.reason);
}

Configure Lock Timeout

For slow migrations, increase the lock timeout:

const migrations = new Migrations(prisma, {
  lockTimeout: 120000,
  lockLeaseDuration: 1800000,
});

Disable Locking (Testing Only)

For unit tests where locking isn’t needed:

const migrations = new Migrations(prisma, {
  disableLocking: true, // Unit tests only
});

Migration Failed Mid-Way

If a migration fails partway through:

  1. Check your database state manually
  2. Fix the SQL in the migration file
  3. Either:
    • Clean up partial changes manually and re-run
    • Write a new migration to continue from current state

SQL Syntax Errors

If you get SQL syntax errors:

  • Check your SQL syntax for your specific database (PostgreSQL, MySQL, SQLite)
  • Test the SQL directly in your database client first
  • Put forward SQL in migration.sql
  • Put executable rollback SQL in down.sql

Rollback Not Working

Some operations are difficult to reverse:

  • Dropping columns - Data is lost permanently
  • Complex data transformations - May not be perfectly reversible

For these cases:

  • Back up data before dropping columns
  • Document manual recovery steps in comments
  • Test rollbacks extensively in staging

Database-Specific Transactions

Prisma wraps each migration in a transaction, but DDL behavior is provider-specific. PostgreSQL and SQLite can roll back most schema changes. MySQL implicitly commits many DDL statements, so inspect and repair the database before retrying a failed migration.

Common Error Messages

”Migration lock timeout”

Another migration is running or a lock is stuck. Wait or use lock release.

”Checksum mismatch for migration X”

The migration file was modified after being applied. Use skipChecksumValidation to recover.

”No pending migrations”

All migrations are already applied. Check with npx prisma-migrations status.

”Migration not found: X”

The migration ID doesn’t exist. Verify with npx prisma-migrations pending.

Getting Help