Prisma — migration shadow database schema mismatch
Prisma migration fails because the shadow database schema does not match the migration history, often after manual schema changes or drift between environments.
Symptoms
- Error: Shadow database is out of sync with migration history
- prisma migrate dev fails with schema drift
- The migration applies manually but not via Prisma CLI
Possible causes
- The database was modified manually outside of Prisma migrations
- Migration files were deleted or edited after being applied
- The shadow database URL points to a database with stale schema
Diagnosis steps
Check migration history
npx prisma migrate statusInterpretation
Shows which migrations are applied and which are pending or drifted.
Reset the shadow database
npx prisma migrate reset --shadow-database-url $SHADOW_URLInterpretation
A reset recreates the shadow DB from migration history.
Root cause
The shadow database used to detect schema drift has a different schema than the migration history expects, so Prisma cannot generate a new migration safely.
Fix
Reset the shadow database, resolve any manual schema changes by creating a migration, and ensure all environments use the same migration history.
Verify the fix
Run prisma migrate dev and confirm a new migration is generated without shadow database errors.
Symptom walkthrough
Prisma migration fails because the shadow database schema does not match the migration history, often after manual schema changes or drift between environments. The error appears in production but may not surface in local development because the conditions that trigger it depend on the deployment environment or runtime configuration. Understanding the full symptom set helps distinguish this issue from similar errors.
Diagnosis in practice
Follow the diagnosis steps in the frontmatter to isolate the cause. Each step includes a command and an interpretation of the output. The goal is to narrow down whether the issue is in the configuration, the runtime, or the application code. Reproduce the error in a minimal setup before applying a fix.
Root cause
The shadow database used to detect schema drift has a different schema than the migration history expects, so Prisma cannot generate a new migration safely.
Fix
Reset the shadow database, resolve any manual schema changes by creating a migration, and ensure all environments use the same migration history. After applying the fix, monitor the system to confirm the error does not recur under load or in different environments.
Verification
Run prisma migrate dev and confirm a new migration is generated without shadow database errors. If the verification passes, the fix is confirmed; if not, re-examine the diagnosis steps for missed contributing factors.
Diagnostic commands
Run these commands to reproduce and diagnose the issue:
npx prisma migrate status
npx prisma migrate reset --shadow-database-url $SHADOW_URL