Skip to content
Get a quote

Supabase migration errorWhy does supabase db push fail, and how do I fix the migration history?

You ran supabase db push and it stopped, often with a message telling you to run migration repair. Often the database itself is fine: the record of which migrations ran no longer matches the files in your repo. Here’s how to find the gap and close it, or hand it over at a fixed price.

Short answer

Supabase keeps a list of the migrations it has run on each database and compares it with the files in supabase/migrations. When the two disagree, db push stops. Back up the live database, link the project with supabase link, then run supabase migration list to see where they split. If someone changed the live database by hand, run supabase db pull to capture that as a migration. If only the list is wrong, migration repair fixes the list without running any SQL.

Find the gap, then close it

  1. 01

    Start with supabase migration list

    “Only the timestamps are compared to identify any differences.” Supabase, CLI reference: db push

    Read the error first: if it names a table, column or lock, skip to the last item. Otherwise link the project with supabase link and list the migrations. Each one shows on two sides, your local files and the live database, and the rows where only one side has it are the problem. Each migration is identified by its timestamp, the long number at the start of its file name, not by the rest of the name. Back up the live database before you change anything.

    supabase migration list

  2. 02

    Someone changed the live database in the dashboard

    “Making schema changes directly on your remote database (via the SQL editor or Table Editor) bypasses the migration history and will cause db push to fail with sync errors.” Supabase, Deploy database migrations

    A common cause. A table or column added in the SQL editor or Table Editor on the live project never went into a migration file, so the history no longer describes the database. Pull the live schema into a new migration file and let the CLI mark it as applied when it asks to update the remote migration history table. Run migration list again: both sides should now match before you push. Commit the file and make every later change through migrations.

    supabase db pull

  3. 03

    The change is there, but the history says it isn’t

    “migration repair updates the tracking table only” Supabase, Deploy database migrations

    If a migration was run by hand, its change is already in the database but missing from the migration history table (Supabase’s list of what has run). Use applied for that case. If the list says a migration ran but its change is not in the database, use reverted. Check the real tables first: repair only edits the list.

    # The change is in the database, but missing from the list
supabase migration repair --status applied <timestamp>

# The list says it ran, but the change is not in the database
supabase migration repair --status reverted <timestamp>

  4. 04

    A migration file the live history has never seen

    “Include all migrations not found on remote history table.” Supabase, CLI reference: db push

    If a migration file is missing from the live history and db push won’t run it, the --include-all flag includes every migration not found there. Run it with --dry-run first to see exactly what would run. If that change is already in the database, repair the history instead, or the SQL runs twice.

    supabase db push --dry-run --include-all

  5. 05

    Two people pushed at the same time

    “Coordinate so only one person runs db push at a time.” Supabase, Deploy database migrations

    Migrations run in timestamp order, so pushes from two machines at once can collide. Agree that one person, or one CI job on merge to main, runs db push.

  6. 06

    The SQL itself failed

    “If a lock timeout error occurs, in your migration file, consider increasing your lock_timeout setting.” Supabase, Deploy database migrations

    If the error names a table, column or lock rather than the history, the migration’s SQL is the problem, and the fix goes in that file. For a lock timeout, Supabase suggests raising lock_timeout in the migration file.

Checked against the vendor’s docs on : Supabase docs: Deploy database migrations; Supabase CLI reference: db push, migration list and migration repair.

Rather hand it over?

Fixed scope, fixed price, paid upfront. The work happens in writing; no call needed.

Related: Supabase staging environment · Supabase project paused · Supabase RLS fixes · Supabase security review before launch

Questions

More on this error

Will migration repair delete my data?

No. It only adds or removes rows in Supabase’s migration history table; it doesn’t run or undo any SQL. The risk is the opposite: if you mark a migration as applied when its change isn’t really there, later pushes skip it. Check the real tables before you repair.

Should I just reset the live database?

No. Run against a linked project, supabase db reset drops everything you created in that database and rebuilds it from your migration files. On a live project with users, close the gap with db pull or migration repair and keep the data.

What access do you need to sort it out?

The repo with its supabase/migrations folder and the output of supabase migration list are enough to find the gap. We write down which commands to run and why, so the commands that change the live history run only after you have read the plan.

Can you fix it for me?

If one bug is the whole problem, the App Fix Ticket covers it: a written diagnosis first, then the fix. If the app has more going on, the Launch Check is a written check of the whole app. Each issue found is rated critical, high, medium or low, with where it is and how it was confirmed. No issues worth fixing, no charge. If the Launch Check finds nothing rated medium or higher, Simon refunds the full $450. You keep the report either way.

A different error?

Describe it and get a written quote

Send the error and what you were doing. You get a written scope, a fixed price and a timeline; we reply by email, usually within one business day.

Describe your problem All fixes