Supabase Branch MIGRATIONS_FAILED: Fix Preview Branch Errors
Your Supabase branch MIGRATIONS_FAILED state means the preview branch could not replay your migration chain. Here is how to read the error, find the broken migration, and get the branch green again.
<!-- BRIEF SPEC (supabase-branching-preview-databases) Variant: PROBLEM-SOLVER | Hook: PROBLEM-AGITATION | FAQ: 3 | ~900-1400 words Cover style: BLUEPRINT (problem-solver) — deep blueprint-blue, white grid; line-art of a branching tree diagram with a red MIGRATIONS_FAILED badge on one branch. No text. In-body images (1): flow diagram showing PR opened -> preview branch created -> migrations replayed sequentially -> MIGRATIONS_FAILED vs ACTIVE_HEALTHY outcomes. SERP Step 0: top results are GitHub issue/commit docs and community troubleshooting notes (no dedicated tutorial exists). Structural gap: none show the full diagnose -> repair -> verify loop with the exact CLI commands and the branch-side vs project-level split. --> Last updated: 2026-10-10 You open a pull request, the Supabase GitHub integration spins up a preview branch, and instead of a working staging database your reviewers get a branch stuck in MIGRATIONS_FAILED . The branch itself is alive — the database is reachable — but your migration chain never applied, so the schema is empty and nothing works. Your PR is now blocked by a database problem that lives nowhere in your application code. Here is the exact loop for diagnosing it, fixing it, and proving the branch recovered. What the supabase branch MIGRATIONS_FAILED state looks like A preview branch that fails its migration replay reports MIGRATIONS_FAILED in the branch list, while the branch's project status often still reads ACTIVE_HEALTHY . That split confuses people: the database server is fine; it is your migration chain that could not be applied. Concretely, the branch has the platform basics (the auth schema, anon and authenticated roles, installed extensions) but none of your application tables, functions, or RLS policies. The Supabase GitHub…