Prisma "P3018: A migration failed to apply" in CI

By Daniel Zoghalchali·Latchkey

A specific migration’s SQL executed and the database rejected it. P3018 includes the database error code and message - the real cause is in that nested error, and it will not pass on retry.

What this error means

prisma migrate deploy starts applying a migration and fails with P3018, embedding the underlying database error (e.g. a duplicate column, missing table, or constraint violation). The same input fails the same way every time.

prisma output

Error: P3018

A migration failed to apply. New migrations cannot be applied before
the error is recovered from.

Migration name: 20240120_add_status_column
Database error code: 42701
Database error: ERROR: column "status" of relation "orders" already exists

Common causes

The migration SQL conflicts with current schema

Adding a column/table/constraint that already exists, or referencing one that does not, makes the database reject the statement. The nested error code pinpoints which.

Data violates a new constraint

Adding a NOT NULL, unique, or foreign-key constraint fails when existing rows violate it. The DDL cannot apply until the data is reconciled.

Migration edited or applied out of order

A migration that was hand-edited after partial application, or run against a database in an unexpected state, can hit objects that already exist or are missing.

How to fix it

Read the embedded database error and fix the SQL

The Database error code/message is the actual problem. Correct the migration so it matches the real schema state.

migration.sql

-- guard against re-adding an existing column
ALTER TABLE "orders" ADD COLUMN IF NOT EXISTS "status" TEXT;

Reconcile data before adding a constraint

For a new NOT NULL/unique/FK, backfill or clean the offending rows first.
Split the change: add the column nullable, backfill, then enforce the constraint in a later migration.
Re-run migrate deploy once the data satisfies the constraint.

Resolve the failed record after fixing

Once corrected, clear the failed migration so deploys can continue (see P3009).

Terminal

npx prisma migrate resolve --rolled-back 20240120_add_status_column
npx prisma migrate deploy

How to prevent it

Test migrations against a copy of production-shaped data, not an empty database.
Use idempotent guards (IF NOT EXISTS) where appropriate.
Add constraints in stages: nullable column → backfill → enforce.

Frequently asked questions

What causes ""P3018: A migration failed to apply""?