dima/supabase
1
0 Fork 0
mirror of https://github.com/supabase/supabase.git synced 2026-10-12 04:45:08 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs(troubleshooting): address review feedback on MIGRATIONS_FAILED guide

Browse Source 
- Promote step headings from h4 to h2 so the heading hierarchy isn't skipped
- Convert sequential step bullets to ordered lists
- Replace "image" placeholder alt text with descriptive alt text
- Use "after" instead of "once" per the docs word list
- Replace the blockquote with a note admonition, as blockquotes aren't used in docs
- Follow the word list elsewhere: "dialog" instead of "popup", drop "e.g." and
  parenthetical asides, and avoid "below" as a location reference
- Don't rely on color alone to identify the failing log entry

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Gn5pGK4dgfXnh68UJ4VYx2
This commit is contained in:
Claude committed 2026-07-29 08:58:10 +00:00
1 parent eb4974819d
commit 803c8a1e38
1 file changed
+31 -27
Download Patch File Download Diff File Expand all files Collapse all files
apps/docs/content/troubleshooting/branch-in-migrations-failed-status.mdx
+31 -27
View File
@@ -5,32 +5,32 @@ keywords = [ "branching", "migrations", "MIGRATIONS_FAILED", "failed" ]
database_id = ""
---
When a Preview Branch is created via the Dashboard, it's built by replaying the migration history from your `main` branch against a fresh database. If that replay fails partway through, the branch is left either empty or partly complete and its status shows `MIGRATIONS_FAILED`. This almost always means the migration history on `main` is out of sync with its actual live schema — commonly because a change was made directly via the SQL Editor or another manual edit that was never captured as a migration file.
When a Preview Branch is created through the Dashboard, it's built by replaying the migration history from your `main` branch against a fresh database. If that replay fails partway through, the branch is left either empty or partly complete and its status shows `MIGRATIONS_FAILED`. This almost always means the migration history on `main` is out of sync with its actual live schema, commonly because a change was made directly in the SQL Editor or through another manual edit that was never captured as a migration file.
Follow the steps below to diagnose and repair your migration history so branching can complete successfully.
Work through the following steps to diagnose and repair your migration history so branching can complete successfully.
---
#### 1. Confirm the branch failure and view its workflow
## 1. Confirm the branch failure and view its workflow
- Go to [Branches](/dashboard/project/_/branches) and find the affected branch.
- Click **View logs**. A popup shows the branch's creation workflow, including the failed step.
1. Go to [Branches](/dashboard/project/_/branches) and find the affected branch.
2. Click **View logs**. A dialog shows the branch's creation workflow, including the failed step.
![image](/docs/img/troubleshooting/migrations-failed-status.png)
![Branch creation workflow logs showing the failed migration step for a branch in MIGRATIONS_FAILED status](/docs/img/troubleshooting/migrations-failed-status.png)
---
#### 2. Find the exact SQL error in your Postgres logs
## 2. Find the exact SQL error in your Postgres logs
- Go to [Postgres Logs](/dashboard/project/_/logs?filter=log_type:eq:postgres).
- Look for entries beginning with `execute <unnamed>:` — these are the individual migration statements being replayed.
- Find the entry **highlighted in red**. This is the statement that failed, and its message explains why (e.g. relation already exists, column not found, permission denied, relation does not exist).
1. Go to [Postgres Logs](/dashboard/project/_/logs?filter=log_type:eq:postgres).
2. Look for entries beginning with `execute <unnamed>:`. These are the individual migration statements being replayed.
3. Find the entry marked as an **error**, which the Dashboard also highlights in red. This is the statement that failed, and its message explains why. Common messages include relation already exists, column not found, permission denied, and relation does not exist.
![image](/docs/img/troubleshooting/postgres-logs-migration-failed.png)
![Postgres Logs with the failed migration statement marked as an error and its message expanded](/docs/img/troubleshooting/postgres-logs-migration-failed.png)
---
#### 3. Prepare a local Supabase environment
## 3. Prepare a local Supabase environment
If you don't already have one, follow the [local development getting started guide](/docs/guides/local-development/cli/getting-started), then link your project:
@@ -40,7 +40,7 @@ supabase link
---
#### 4. Pull down your production migration history
## 4. Pull down your production migration history
```bash
supabase migration fetch
@@ -50,33 +50,37 @@ This retrieves the migration files currently recorded against your `main` branch
---
#### 5. Repair the culprit migration
## 5. Repair the culprit migration
- Locate the migration file containing the SQL statement that matches the red error from step 2, and correct it so it reflects the real state of your production schema.
- Once fixed, mark it as applied using its timestamp:
1. Locate the migration file containing the SQL statement that matches the error you found in step 2, and correct it so it reflects the real state of your production schema.
2. After correcting the file, mark it as applied using its timestamp:
```bash
supabase migration repair <timestamp> --status applied
```
```bash
supabase migration repair <timestamp> --status applied
```
- Verify the repair took effect by checking [production migrations](/dashboard/project/_/database/migrations) in the Dashboard.
3. Verify the repair took effect by checking [production migrations](/dashboard/project/_/database/migrations) in the Dashboard.
---
#### 6. Re-test branch creation
## 6. Re-test branch creation
Once repaired, either create a new branch or **rebase** the existing affected branch.
After repairing the migration history, either create a new branch or **rebase** the existing affected branch.
![image](/docs/img/troubleshooting/rebase-branch-button.png)
![The rebase branch button in the Dashboard branch details view](/docs/img/troubleshooting/rebase-branch-button.png)
Check the branch's workflow logs again (step 1) to confirm migrations now complete successfully.
Check the branch's workflow logs again, as described in step 1, to confirm migrations now complete successfully.
> If it fails again, repeat steps 2–6 — there may be more than one out-of-sync migration to work through, one at a time.
<Admonition type="note">
Branch creation can fail more than once because more than one migration is out of sync. Each failure surfaces the next problem statement, so repeat steps 2 through 6 to work through them one at a time.
</Admonition>
---
#### Additional tips
## Additional tips
If issues persist after repairing migration history (schema drift, repeated mismatches), review the [branching troubleshooting documentation](/docs/guides/deployment/branching/troubleshooting#migration-issues) and consider further manual repair with [`supabase migration repair`](/docs/reference/cli/supabase-migration-repair).
If issues persist after repairing migration history, such as schema drift or repeated mismatches, review the [branching troubleshooting documentation](/docs/guides/deployment/branching/troubleshooting#migration-issues) and consider further manual repair with [`supabase migration repair`](/docs/reference/cli/supabase-migration-repair).
If your migration history has drifted too far out of sync for repairing individual migrations to be practical, consider creating a single baseline migration that encapsulates your production project's current schema instead. The [new branch doesn't copy database troubleshooting guide](/docs/guides/troubleshooting/new-branch-doesnt-copy-database) walks through the commands for setting this up.