Database Migration Errors

How to resolve Prisma migration failures in CI/CD and production deployments.

What Are Database Migration Errors?

Database migration errors occur when Prisma migration files have conflicts or issues that prevent them from running successfully. These errors typically appear in GitHub Actions during:

• Create Neon Branch — when deploying a PR to a preview environment
• Apply Migrations to Neon Main — when merging to the main branch

Common causes include:

• Duplicate CREATE TABLE statements from multiple PRs
• Missing or inconsistent schema definitions
• Failed migrations that block new ones

Symptoms

You will see errors like:

Error: P3009
migrate found failed migrations in the target database, new migrations will not be applied.

A]migrate resolve --rolled-back 20260401071036_pr576_23836534312

to remove it from the database migrations table.
Read more about how to resolve migration issues in a production database:
https://pris.ly/d/migrate-resolve

Or you may see unrelated tables being affected in migration output — this is a sign that your branch was not created from the latest main.

Step 1: Ensure Your Branch Is Up to Date

Before troubleshooting, make sure your branch has the latest changes from main:

git checkout main
git pull origin main
git checkout your-feature-branch
git merge main

If your branch was created from an outdated main, you may see migration changes for unrelated tables. This indicates the branch needs to be rebased or recreated.

In many cases, the simplest fix is to close the current PR, update your branch from main, and open a new PR:

Step 2: Diagnose the Issue

Copy the error from the failing GitHub Action and ask Claude to analyze it:

After receiving Claude's analysis, report the issue and Claude's recommendation to the Vibe Coding Planner (your team's IT staff or project lead) before proceeding. They can help validate the diagnosis and advise on the safest fix.

Step 3: Fix the Migration Files

Based on Claude's recommendations, you may need to:

1. Remove duplicate CREATE TABLE statements — if multiple PRs created the same table
2. Update schema.prisma — ensure it matches the expected database state
3. Remove conflicting migrations — if they conflict with already-applied changes

Important: Be careful not to drop tables or columns that belong to other applications.

Danger Zone: Steps 4 and beyond involve directly modifying the database. These actions must be validated and approved by IT staff before proceeding. Incorrect rollbacks can cause data loss or break other applications.

Step 4: Roll Back Failed Migrations

After pushing your fix, the GitHub Action may still fail because a failed migration is recorded in the database. You need to roll it back.

Copy the new error and ask Claude for rollback commands:

Step 5: Run the Rollback Commands

1. Get the DATABASE_URL for your branch from the Railway service under "Variables"
2. Run the rollback command locally:

DATABASE_URL="postgresql://your-connection-string" \
pnpm --filter database exec prisma migrate resolve --rolled-back 20260401071036_migration_name

3. Re-run the GitHub Action after the rollback completes

If the Error Occurs After Merging to Main

If the migration fails after your PR is merged to main:

1. Create a new branch from main
2. Copy the error from the failing merge-main-neon-cleanup action
3. Follow steps 2-5 above to diagnose and fix the issue
4. Push the fix as a new PR

Safety Net: Point-in-Time Recovery

If something goes wrong after merging to main, Neon provides point-in-time recovery. Contact your team lead or database administrator to:

1. Restore the database to a point before the problematic merge
2. Re-apply the correct migrations

Note: Point-in-time recovery should only be used as a last resort after other fixes have failed.

Checklist Before Merging

Before merging any PR with database changes:

• Branch created from latest main
• schema.prisma is up to date
• Migration files do not conflict with existing tables
• No duplicate CREATE TABLE statements
• Preview deploy succeeded
• All CI checks passed

Quiz