Wrangler D1 "migrations failed" to apply in CI

By Daniel Zoghalchali·Latchkey

A D1 migration ran and returned an error. The cause is usually a SQL statement that failed against the remote database, or applying to the wrong target because --remote was omitted so it hit the local dev DB instead.

What this error means

A wrangler d1 migrations apply step reports a failed migration with the failing SQL and an error, and exits non-zero.

🌀 Executing on remote database my-db:
✘ [ERROR] Migration 0002_add_index.sql failed.
  table users has no column named email

Common causes

A SQL error in the migration

A statement references a column, table, or constraint that does not exist in the current schema, so the migration aborts.

Applied to the wrong target

Without --remote, migrations apply to the local simulated database, so CI can drift from the real remote one.

How to fix it

Apply to the remote database explicitly

1. Add --remote so migrations run against the real D1 database.
2. Fix the failing SQL so it matches the current schema.
3. Re-run; already-applied migrations are skipped.

npx wrangler d1 migrations apply DB --remote

Keep migrations ordered and idempotent

Number migrations sequentially and guard statements (IF NOT EXISTS) so a partial re-run does not fail.

CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, email TEXT);

How to prevent it

• Always pass --remote in CI so the real database is migrated.
• Guard schema statements with IF NOT EXISTS where possible.
• Test migrations against a copy before deploying.

Frequently asked questions

Related guides

References

• Terraform documentation
• GitHub Actions documentation