Prisma Migration Error— Fixed [Complete Guide 2026]
Also covers: schema drift · failed migration state · shadow database · production deploy
⚡ Diagnose the Error First
# See full migration status — which are applied, pending, failed
npx prisma migrate status
# In development — resets DB and re-applies all migrations
npx prisma migrate reset
# In production — apply pending migrations only (safe)
npx prisma migrate deployRead the Migration Error Message First
Prisma migration errors fall into a few distinct categories. The error message tells you which one you are dealing with. Common patterns:
- Drift detected: Database schema is not in sync with migration history
- Migration is in failed state: A previous migration partially applied and errored
- Shadow database error: Prisma cannot create the temp database for diff computation
- Migration already applied but differs: Migration file was modified after being applied
Schema Drift Detected
Database was manually altered outside PrismaDrift happens when someone runs raw SQL directly against the database — adding a column, creating an index, changing a type — without a corresponding Prisma migration.
Error: P3006
The migration `20260101_add_users` failed to apply cleanly to the shadow database.
Error: column "name" of relation "User" already exists# Step 1: See what Prisma thinks has drifted
npx prisma migrate status
# Step 2: If the drift matches what you want, create a baseline migration
# This tells Prisma "the DB is correct, mark existing state as baseline"
npx prisma migrate resolve --applied "20260101_baseline"
# Step 3: If you want to sync schema.prisma TO the DB (pull from DB)
npx prisma db pull # updates schema.prisma to match actual DB
# Step 4: Generate a new migration from the updated schema
npx prisma migrate dev --name sync_driftIn development, prisma migrate reset is the fastest fix — it drops the database, recreates it, and applies all migrations cleanly. Only use in dev environments.
Migration in Failed State
A migration partially applied then erroredWhen a migration fails midway, Prisma marks it as failed in the _prisma_migrations table. You must resolve this before running new migrations.
Error: P3009
migrate found failed migrations in the target database,
new migrations will not be applied. Read more about how to resolve a
failed migration: https://pris.ly/d/migrate-resolve
Migration name: 20260115_add_orders_table
Status: failed# Option A: Fix the SQL error in the migration file, then mark as applied
# 1. Edit prisma/migrations/20260115_add_orders_table/migration.sql
# 2. Mark as applied
npx prisma migrate resolve --applied "20260115_add_orders_table"
# Option B: Mark as rolled back, delete the file, recreate
npx prisma migrate resolve --rolled-back "20260115_add_orders_table"
rm -rf prisma/migrations/20260115_add_orders_table
npx prisma migrate dev --name add_orders_tableShadow Database Errors
Managed databases — Neon, PlanetScale, SupabasePrisma needs a shadow database to safely compute migration diffs. Managed databases often restrict CREATE DATABASE permissions, causing this to fail.
Error: P3014
Prisma Migrate could not create the shadow database. Please make sure the
database user has permission to create databases.datasource db {
provider = "postgresql"
url = env("DATABASE_URL")
// Point to a separate database for shadow operations
shadowDatabaseUrl = env("SHADOW_DATABASE_URL")
}DATABASE_URL="postgresql://user:pass@host:5432/mydb"
# Create a separate empty database for shadow operations
SHADOW_DATABASE_URL="postgresql://user:pass@host:5432/mydb_shadow"On Neon or Supabase, create a second branch/database named mydb_shadow and point SHADOW_DATABASE_URL to it. This is a one-time setup.
Already Applied Migration Was Changed
Never edit applied migration filesError: P3005
The database schema is not empty. Read more about how to baseline an existing
production database: https://pris.ly/d/migrate-baselineIf you edited a migration file after it was already applied to any environment, Prisma detects the checksum mismatch and refuses to proceed.
# Never edit applied migration files. Instead:
# 1. Revert the migration file to its original content (use git)
git checkout prisma/migrations/20260101_initial/migration.sql
# 2. Create a new migration for the additional changes
npx prisma migrate dev --name add_missing_changes
# If you truly cannot revert, mark the migration as resolved
# (use only in emergencies — prefer the git revert approach)
npx prisma migrate resolve --applied "20260101_initial"Never edit a migration file that has been applied to any database — development, staging, or production. Create a new migration instead.
Production Migration Best Practices
migrate deploy · pre-deploy hooks · rollback strategy# CORRECT — use migrate deploy in production (not migrate dev)
npx prisma migrate deploy
# migrate deploy:
# ✓ Applies only pending migrations
# ✓ Never resets or drops data
# ✓ Never creates new migrations
# ✓ Safe to run in CI/CD pipelines
# migrate dev:
# ✗ Creates new migrations interactively
# ✗ Resets database when conflicts found
# ✗ Never run in production{
"scripts": {
"db:migrate": "prisma migrate deploy",
"db:status": "prisma migrate status",
"start": "npm run db:migrate && node server.js"
}
}- name: Run database migrations
run: npx prisma migrate deploy
env:
DATABASE_URL: secrets.DATABASE_URL
- name: Start application
run: npm startPrevention Checklist
- Never alter the database manually (raw SQL) — always use Prisma migrations
- Never edit a migration file after it has been applied to any environment
- Use migrate deploy in production, never migrate dev
- Set SHADOW_DATABASE_URL when using managed databases like Neon or Supabase
- Run npx prisma migrate status in your CI pipeline to catch drift early
- Commit migration files to git — never .gitignore the prisma/migrations folder
Frequently Asked Questions
What is Prisma schema drift?+−
How do I fix 'The migration was not applied because it triggered an error' in Prisma?+−
How do I reset Prisma migrations in development?+−
What is the Prisma shadow database and why does it fail?+−
Can I run Prisma migrations in production safely?+−
How do I fix 'migration already exists in the database but is not in the migration folder'?+−
Need Expert Help?
We Manage Prisma Migrations in Production
Softplix handles database schema management, migration pipelines, and Prisma setup for production Node.js applications. Let us take migrations off your plate.
Talk to an Engineer