Common Migration Errors
Migrations can occasionally run into issues, especially when moving data between instances with different configurations. This guide covers the most common errors you might see during a Stack2X migration and how to resolve them.
Timeout Errors
What it looks like: "Migration timed out" or "Operation exceeded time limit"
What it means: The migration took longer than the allowed time to complete. This usually happens with large databases or when the target instance is under heavy load.
How to fix it:
- Try running the migration during off-peak hours when your instances have less traffic.
- Break the migration into smaller pieces by selecting fewer components at a time. For example, migrate the database first, then storage separately.
- Check that both your source and target instances are responsive. A slow instance can cause the entire migration to time out.
Permission Denied
What it looks like: "Permission denied" or "Insufficient privileges"
What it means: Stack2X doesn't have the necessary access to read from the source or write to the target instance.
How to fix it:
- For Supabase Cloud instances, re-authorize the OAuth connection to make sure write scopes are granted. See OAuth Scope Issues for step-by-step instructions.
- For self-hosted instances, verify that the database user in your connection credentials has the required privileges. The user needs both read and write access to the schemas being migrated.
Schema Conflicts
What it looks like: "Schema conflict detected" or "Table already exists with different structure"
What it means: The target instance already has tables or objects that conflict with what the migration is trying to create. For example, a table with the same name but different columns.
How to fix it:
- Review the conflict details shown in the error message. Stack2X tells you exactly which objects are in conflict.
- Choose whether to keep the target's version, overwrite it with the source, or merge the changes. Stack2X's conflict resolution tool helps you make this decision for each conflict.
- If you're migrating to a fresh instance, this error usually means a previous partial migration left behind some objects. Consider clearing the target before retrying.
Storage Upload Failures
What it looks like: "Failed to upload file" or "Storage write error"
What it means: Stack2X couldn't upload one or more files to the target instance's storage. This can happen if a file exceeds the target's size limit, if the storage bucket doesn't exist, or if there's a network interruption.
How to fix it:
- Check that the target instance's storage buckets exist and have enough space.
- Verify that individual file size limits on the target instance accommodate your files.
- Retry the migration -- transient network issues often resolve on a second attempt.
Auth Migration Errors
What it looks like: "Failed to migrate auth users" or "Auth provider configuration mismatch"
What it means: The target instance's auth configuration doesn't match the source. For example, the source uses a third-party auth provider that isn't configured on the target.
How to fix it:
- Set up the same auth providers on the target instance before migrating. Make sure provider configurations (client IDs, secrets, redirect URLs) are in place.
- If you don't need to migrate all auth providers, use a selective migration and exclude auth from the components.