# Troubleshooting

Common issues and solutions for Supabase branching

Common issues and solutions for Supabase branching.

This guide covers common issues you might encounter when using Supabase branching and how to resolve them.

## Monitoring deployments

To check deployment status and troubleshoot failures:

1. Open the Supabase Dashboard
2. Navigate to "Manage Branches"
3. Click on your branch to view deployment logs
4. Check the "View logs" section for detailed error messages

Each step in a workflow run reports one of these statuses:

| Status    | Meaning                                                                             |
| --------- | ----------------------------------------------------------------------------------- |
| `CREATED` | The step hasn't started.                                                            |
| `RUNNING` | The step is in progress.                                                            |
| `EXITED`  | The step succeeded.                                                                 |
| `PAUSED`  | The step finished with a warning, or was skipped on purpose. Later steps still run. |
| `DEAD`    | The step failed. Steps that depend on it don't run.                                 |

A failed health check is a warning. The `health` step shows `PAUSED` and the workflow continues. A `DEAD` `migrate` step stops the `seed` and `deploy` steps.

For programmatic monitoring, you can use the [Management API](https://api.supabase.com/api/v1#tag/environments/post/v1/projects/\{ref}/branches) to poll branch status.

For detailed troubleshooting guidance, see our [Troubleshooting guide](/docs/guides/deployment/branching/troubleshooting).

## Common issues

### Rolling back migrations

You might want to roll back changes you've made in an earlier migration change. For example, you may have pushed a migration file containing schema changes you no longer want.

To fix this, push the latest changes, then delete the preview branch in Supabase and reopen it.

The new preview branch is a fresh clone of your base project and is reseeded from the `./supabase/seed.sql` file by default. Any additional data changes made on the old preview branch are lost.

To rerun migrations that your base project has already applied, reset the branch from the Supabase Dashboard instead. A reset reruns all migrations in sequential order and drops existing data on the branch.

### Deployment failures

A deployment might fail for various reasons, including invalid SQL statements and schema conflicts in migrations, errors within the `config.toml` config, or something else.

To check the error message, see the Supabase workflow run for your branch under the [View logs](/dashboard/project/_/branches) section.

### Schema drift between preview branches

If multiple preview branches exist, each preview branch might contain different schema changes. This is similar to Git branches, where each branch might contain different code changes.

When a preview branch is merged into the production branch, it creates a schema drift between the production branch and the preview branches that haven't been merged yet.

These conflicts can be resolved in the same way as normal Git Conflicts: merge or rebase from the production Git branch to the preview Git branch. Since migrations are applied sequentially, ensure that migration files are timestamped correctly after the rebase. Changes that build on top of earlier changes should always have later timestamps.

If you manage your schema with [declarative schema files](/docs/guides/local-development/declarative-database-schemas), resolve the drift in the schema files instead. Delete the migrations your branch generated, then run `supabase db schema declarative sync` to regenerate them. The regenerated migration gets a new timestamp, so it orders after existing migrations without renaming files by hand.

### Changing production branch

You cannot change which project branch serves as the production branch — the base project that all branches are created from will always remain the production branch. However, you can update which GitHub branch is linked to your production branch. To do this, go to the [Integrations page](/dashboard/project/_/settings/integrations) and change the production branch name.

## Migration issues

### Failed migrations

When migrations fail, check:

1. **SQL syntax**: Ensure your migration files contain valid SQL
2. **Dependencies**: Check if migrations depend on objects that don't exist
3. **Permissions**: Verify the migration doesn't require superuser privileges

To debug:

```bash
# Test migrations locally first
supabase db reset

# Check migration logs in the dashboard
# Navigate to Branches > Your Branch > View Logs
```

### Permission denied errors on a new branch

If the Data API returns `42501` permission denied errors on a branch for tables or functions that work on your base project, the branch is missing default privileges on the `public` schema. New branches are created without them, and only your migrations can grant them back.

Check whether your initial migration contains `alter default privileges ... grant` statements for the `public` schema. If it doesn't, see [Default privileges on branches](/docs/guides/deployment/branching/working-with-branches#default-privileges-on-branches) for how to add them, or [grant access explicitly](/docs/guides/api/securing-your-api#grant-access-explicitly) in a migration.

### Migration order problems

Migrations must run in the correct order. Common issues:

1. **Timestamp conflicts**: Ensure migration files have unique timestamps
2. **Dependency issues**: Later migrations depending on earlier ones
3. **Rebase problems**: Timestamps getting out of order after Git rebase

Fix by:

```bash
# Rename migration files to fix timestamp order
mv 20240101000000_old.sql 20240102000000_old.sql

# Reset local database to test
supabase db reset
```

Within a single migration generated on the [`pg-delta`](/docs/guides/local-development/diff-engines) engine (`supabase db diff` or `db schema declarative sync`), you don't need to reorder statements by hand, because the engine orders them by dependency. Migrations generated separately, such as on two branches that later merge, still need correct relative timestamps, so rename or regenerate them as shown above. A single sync can write split files that share a name (`_1`/`_2` suffixes) with timestamps one second apart. The CLI applies them in timestamp order, so renaming one file of a split pair in a way that changes that order breaks the sequence. Regenerate the migration instead. See [Cleaning up generated migrations](/docs/guides/local-development/cli-workflows#cleaning-up-generated-migrations).

## Connection issues

### Cannot connect to preview branch

If you can't connect to a preview branch:

1. **Check credentials**: Ensure you're using the correct branch-specific credentials
2. **Auto-pause**: The branch might be paused. It will resume on the first request
3. **Network restrictions**: Check if network restrictions are blocking access

### Connection timeouts

Preview branches auto-pause after inactivity. First connections after pause may timeout:

1. **Retry**: The branch will wake up after the first request
2. **Persistent branches**: Convert frequently-used branches to persistent

## Configuration problems

### Config.toml not applying

If configuration changes aren't applying:

1. **Syntax errors**: Validate your `config.toml` syntax
2. **Git sync**: Ensure changes are committed and pushed
3. **Branch refresh**: Try deleting and recreating the branch
4. **Persistent branch**: Configuration runs on a persistent branch, including your production branch, only when a `[remotes]` block names its project ID. For the `[remotes]` syntax, see [Remote-specific configuration](/docs/guides/deployment/branching/configuration#remote-specific-configuration)
5. **Section not applied by branching**: The `configure` step applies only the `[db]`, `[api]`, `[auth]`, `[storage]`, and `[experimental]` sections. For which steps read the other sections, see [Configuration](/docs/guides/deployment/branching/github-integration#configuration)

### Secrets not available

If secrets aren't working in your branch:

1. **Branch-specific**: Remember secrets are set per branch
2. **Syntax**: Use correct syntax: `env(SECRET_NAME)`
3. **CLI version**: Ensure you're using the latest CLI version

## Performance issues

### Slow branch creation

Branch creation might be slow due to:

1. **Large migrations**: Many or complex migration files
2. **Seed data**: Large seed files take time to process
3. **Network latency**: Geographic distance from the branch region

### Query performance

Preview branches may have different performance characteristics:

1. **Cold starts**: First queries after auto-pause are slower
2. **Resource limits**: Preview branches have different resource allocations
3. **Indexing**: Ensure proper indexes exist in your migrations

## Data issues

### Seed data not loading

If seed data isn't loading:

1. **File location**: Ensure `seed.sql` is in `./supabase/` directory
2. **SQL errors**: Check for syntax errors in seed file
3. **Dependencies**: Seed data might reference non-existent tables

### Data persistence

Remember that preview branch data:

1. **Is temporary**: Data is lost when branch is deleted
2. **Isn't migrated**: Data doesn't move between branches
3. **Resets on recreation**: Deleting and recreating branch loses data

## Getting help

If you're still experiencing issues:

1. **Check logs**: Review branch logs in the Supabase Dashboard
2. **Community**: Ask in [GitHub discussions](https://github.com/orgs/supabase/discussions/18937)
3. **Support**: Contact support for project-specific issues
4. **Documentation**: Review the latest documentation for updates