How to fix P3006: Migration failed to apply cleanly to the shadow database in Prisma

PrismaINTERMEDIATEHIGHUpdated Dec 29, 2025· 175 views

This error occurs when Prisma's shadow database (used for detecting schema drift) cannot apply your migrations cleanly. Common causes include schema drift, permission issues, manual database changes, or conflicting migrations. Resolve it by resetting your database, syncing your schema, or fixing permissions.

Quick fix

Fixes P3006: Migration failed to apply cleanly to the shadow database

npx prisma migrate dev
  1. Check the detailed error message
  2. Check for manual database changes
  3. Verify your Prisma schema matches your migrations
  4. Run prisma db pull to re-baseline your schema
prisma — error
npx prisma migrate dev
P3006: Migration failed to apply cleanly to the shadow database
shell
npx prisma migrate dev

What this error means

The P3006 error occurs when Prisma Migrate cannot apply your migration to the shadow database during development. The shadow database is a temporary, automatically-created database that Prisma uses to detect schema drift and ensure migrations are safe before applying them to your actual development database. When a migration fails to apply cleanly to this shadow database, it indicates a mismatch between your migration files, your Prisma schema, and your actual database state. This could mean your schema is out of sync with your migration history, permissions are insufficient, or the database was modified manually outside of Prisma Migrate.

Typical symptoms

  • Error message "P3006: Migration {name} failed to apply cleanly to the shadow database" when running prisma migrate dev
  • Migration works on your development database but fails on the shadow database
  • The error mentions a specific SQL issue like "relation already exists" or "column does not exist"
  • You switched between git branches and now migrations fail
  • You manually edited the database outside of Prisma and now migrations cannot apply
  • Permission errors like "permission denied" or "could not create trigger"

Common causes

  1. Database schema drift: Your development database was manually modified or has uncommitted manual schema changes that don't match your Prisma schema or migration files
  2. Manual migration edits: You edited a migration file after it was already applied to the database
  3. Database permission issues: The database user lacks permissions to create/drop tables, indexes, or triggers needed by the migration
  4. Switching git branches: Moving between branches with different migration histories can cause conflicts if migrations were partially applied
  5. Prisma schema out of sync: Your schema.prisma file does not match your migration files or database state
  6. Uncommitted changes in version control: Migration files exist in your database history but not in your current git branch
  7. Character encoding or syntax issues: The migration SQL has UTF-8 BOM encoding or invalid syntax for your database

How to fix "P3006: Migration failed to apply cleanly to the shadow database"

1Check the detailed error message

Run the migration command with verbose output to see exactly what failed:

bash
npx prisma migrate dev

Read the full error message—it will tell you which table, column, or constraint is causing the issue. For example:

bash
ERROR: relation "PageContents" already exists

This tells you the specific conflict blocking the migration.

2Check for manual database changes

Verify that your development database matches your migration history. Use a database client (psql, MySQL CLI, or Prisma Studio) to inspect the current schema:

bash
npx prisma studio

Or connect directly:

bash
psql $DATABASE_URL -c "\dt"  # PostgreSQL: list tables
mysql -u user -p < "SHOW TABLES;"  # MySQL

If you see tables or columns that shouldn't exist (created manually or by other tools), you need to remove them or document them in your migrations.

3Verify your Prisma schema matches your migrations

Compare your prisma/schema.prisma with your migration files:

bash
ls -la prisma/migrations/
cat prisma/migrations/*/migration.sql

Your schema.prisma should represent the END state of all your migrations. If it doesn't, edit schema.prisma to match, then generate a new migration:

bash
npx prisma migrate dev --name fix_schema_sync
4Run prisma db pull to re-baseline your schema

If your database and schema are out of sync, pull the current database state into your Prisma schema:

bash
npx prisma db pull

This introspects your actual database and updates schema.prisma. Review the changes carefully, then create a migration to document this state:

bash
npx prisma migrate dev --name baseline_from_db
5Reset your development database (if safe)

If you're in active development and the data in your dev database doesn't matter, reset the database to a clean state:

bash
npx prisma migrate reset

This will:
1. Drop the database
2. Recreate it
3. Run all migrations from scratch
4. Re-seed with your seed data

Warning: Only use this in development. Never run this in production.

6Check and fix database permissions

If the error mentions "permission denied" or similar, ensure your database user has sufficient privileges:

For PostgreSQL:

sql
ALTER USER your_user CREATEDB;
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO your_user;
GRANT ALL PRIVILEGES ON ALL SEQUENCES IN SCHEMA public TO your_user;
GRANT USAGE ON SCHEMA public TO your_user;

For MySQL:

sql
GRANT ALL PRIVILEGES ON *.* TO 'your_user'@'localhost';
FLUSH PRIVILEGES;

Alternatively, configure a separate shadow database user with full permissions.

7Configure a separate shadow database (if needed)

If your hosting provider (e.g., Azure, some managed databases) doesn't allow automatic shadow database creation, specify one manually in schema.prisma:

prisma
datasource db {
  provider          = "postgresql"
  url               = env("DATABASE_URL")
  shadowDatabaseUrl = env("SHADOW_DATABASE_URL")
}

Then in your .env.local:

bash
DATABASE_URL=postgresql://user:password@host/production_db
SHADOW_DATABASE_URL=postgresql://user:password@host/shadow_db

Create the shadow database manually and ensure it's empty before running migrations.

8Resolve conflicting migrations

If you switched git branches and have conflicting migrations in your history, use prisma migrate resolve to mark migrations as rolled back:

bash
npx prisma migrate resolve --rolled-back migration_name_here

Then run:

bash
npx prisma migrate dev

This reconciles your migration history without forcing a full reset.

9Review migration file syntax

If the error persists, check for syntax issues in your latest migration file:

bash
cat prisma/migrations/*/migration.sql | tail -20

Ensure:
- File is saved as UTF-8 (not UTF-8 with BOM)
- SQL syntax is valid for your database
- Table/column names are properly quoted if needed

If you find an issue, edit the migration SQL file directly (before applying it) or delete the unapplied migration and recreate it.

Advanced notes

Schema Drift Explanation: Prisma compares the end state of your migration history (replayed in the shadow database) against your actual development database. If they don't match, schema drift is detected. This can happen when: (1) you manually alter the database with raw SQL outside of Prisma, (2) you use prisma db push instead of migrate, or (3) migrations are applied partially. To prevent this, always use Prisma Migrate for schema changes and commit migration files to git. Cloud-Hosted Databases: Some managed databases (Heroku, Azure, DigitalOcean) have restrictions on creating/dropping databases. For these, you must either: (a) create a shadow database manually and configure shadowDatabaseUrl, or (b) use prisma db push for prototyping instead of prisma migrate dev. Git Branch Conflicts: When merging branches with different migrations, always re-run your migrations after merging. If branch A and B both added migrations independently, their order might conflict. Use git rebase or manually resolve conflicts in the migrations folder. If you have duplicate migration timestamps, rename them with unique dates.

Frequently asked questions

What does "P3006: Migration failed to apply cleanly to the shadow database" mean?
The P3006 error occurs when Prisma Migrate cannot apply your migration to the shadow database during development. The shadow database is a temporary, automatically-created database that Prisma uses to detect schema drift and ensure migrations are safe before applying them to your actual development database. When a migration fails to apply cleanly to this shadow database, it indicates a mismatch between your migration files, your Prisma schema, and your actual database state.
How do I fix "P3006: Migration failed to apply cleanly to the shadow database"?
This error occurs when Prisma's shadow database (used for detecting schema drift) cannot apply your migrations cleanly. Common causes include schema drift, permission issues, manual database changes, or conflicting migrations. Resolve it by resetting your database, syncing your schema, or fixing permissions.
What causes "P3006: Migration failed to apply cleanly to the shadow database"?
Database schema drift: Your development database was manually modified or has uncommitted manual schema changes that don't match your Prisma schema or migration files Manual migration edits: You edited a migration file after it was already applied to the database Database permission issues: The database user lacks permissions to create/drop tables, indexes, or triggers needed by the migration
Is the "P3006: Migration failed to apply cleanly to the shadow database" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading