Skip to main content

​
Overview

This guide covers common issues you might run into when importing a database to PlanetScale and how to fix them. Most problems show up when you create the external keyspace. Run pscale keyspace create-external with --dry-run to check your source database without creating anything. Connection, server configuration, and user grant errors stop the external keyspace from being created. Schema errors are listed for each table but don’t block creation.

​
Connection issues

​
Can’t connect to external database

If PlanetScale can’t connect to your database, here’s what to check: Verify your credentials locally Try connecting with the same credentials using the MySQL CLI:
If this works locally but not in PlanetScale, the issue is likely network-related. Check IP allowlist Make sure you’ve added all PlanetScale IP addresses to your database’s firewall or security group. The specific IPs depend on which region you selected for your PlanetScale database. See our Import public IP addresses page. Verify database is publicly accessible PlanetScale needs to reach your database over the internet. Check that:
  • Your database has a public IP address
  • Public access is enabled in your database settings
  • No VPN or private network is required
SSL/TLS issues If you’re getting SSL-related errors:
  • Try --ssl-mode disabled to test if SSL is the issue
  • If your database uses self-signed certificates, provide the full CA certificate chain
  • For managed databases (RDS, Azure, etc.), use --ssl-mode required or --ssl-mode verify_ca

​
Connection times out

If the connection attempt times out: Firewall rules Most timeouts are caused by firewall rules blocking PlanetScale IPs. Double-check:
  • All IPs for your region are allowlisted
  • The port (usually 3306) is open
  • Any cloud provider security groups are configured correctly
Database not running Verify your database server is running and accepting connections. Hostname/port incorrect Make sure you’re using the correct hostname and port. For cloud providers:
  • Use the cluster endpoint, not individual instance endpoints
  • Default MySQL port is 3306, but some providers use different ports (DigitalOcean uses 25060)

​
Server configuration errors

​
GTID mode is OFF

Error: external database settings are not compatible with PlanetScale: "gtid_mode" must be "ON", but found: "OFF" Solution: You need to enable GTID mode in your database configuration. For AWS RDS/Aurora:
  1. Create a custom DB parameter group
  2. Set gtid-mode to ON
  3. Set enforce_gtid_consistency to ON
  4. Apply the parameter group to your database
  5. Reboot the database
For Azure:
  1. Go to Server parameters
  2. Set gtid_mode to ON (you may need to go through intermediate states: OFF_PERMISSIVE → ON_PERMISSIVE → ON)
  3. Set enforce_gtid_consistency to ON
  4. Save changes
For self-hosted MySQL/MariaDB: Add to your my.cnf or my.ini:
Then restart MySQL.

​
Binary logging not enabled

Error: external database settings are not compatible with PlanetScale: "log_bin" must be "ON", but found: "OFF" Solution: For AWS RDS/Aurora: Binary logging is tied to automated backups. Enable automated backups with a retention period >= 2 days. For GCP Cloud SQL: Enable Point in Time Recovery (PITR) from the console. For self-hosted: Add to your configuration:
Restart MySQL.

​
Wrong binlog format

Error: "binlog_format" must be "ROW", but found: "MIXED" or "STATEMENT" Solution: Set binlog_format to ROW in your database configuration, then restart. If you see "binlog_row_image" must be "FULL" or "NOBLOB", set binlog_row_image to FULL. For managed databases, update this in your parameter group or server parameters.

​
Binlog retention too short

Error: "binlog_expire_logs_seconds" must be > 172800 (or similar for expire_logs_days). On AWS RDS and Aurora: "binlog retention hours" must be at least 48 hours or binlog retention is not set on this AWS RDS database. Solution: You need at least 48 hours of binlog retention for the import to work. For AWS RDS/Aurora:
Verify with:
For other platforms: Set in your database configuration:
Or:

​
sql_mode is not compatible

Error: "sql_mode" cannot have "ANSI_QUOTES" enabled or PlanetScale requires "sql_mode" to have the following options set: "NO_ZERO_IN_DATE, NO_ZERO_DATE" Solution: Remove ANSI_QUOTES from sql_mode, and make sure it includes NO_ZERO_IN_DATE and NO_ZERO_DATE. For managed databases, update this in your parameter group or server parameters.

​
max_connections is too low

Error: PlanetScale requires external databases to support at least a max connection limit of 10 Solution: Set max_connections to at least 10. PlanetScale uses up to half of your max_connections for the import.

​
Unsupported MySQL version

Error: unsupported MySQL version detected Solution: MySQL 5.6, 5.7, and 8.0 are supported. Contact support if you need to import from a different version.

​
Existing _vt database

Error: external database may have existing Vitess state: found "_vt" Vitess state database Solution: Your source database already has a _vt database, usually left behind by an earlier Vitess-based import or replication tool. Make sure nothing is using it, then drop it and try again:

​
Schema compatibility issues

​
No unique key on table

Error: Table has no unique key Solution: All tables must have a unique, not-null key. This is required for replication to work correctly. Add a primary key or unique index to the table:
Or add a unique index:
See our Changing unique keys documentation for more details.

​
Invalid charset

Error: Table uses unsupported charset Solution: PlanetScale supports: utf8, utf8mb4, utf8mb3, latin1, and ascii. Convert your table to a supported charset:
We recommend utf8mb4 as it has the widest character support.

​
Table names with special characters

Error: Table name contains unsupported characters Solution: Rename tables that have characters outside the standard ASCII set:
Ensure that any queries using the table name get updated as well.

​
Views detected

Views aren’t imported automatically. After your import completes, you’ll need to manually recreate any views in your PlanetScale database.

​
Unsupported storage engine

Error: Table uses non-InnoDB storage engine Solution: Convert your tables to InnoDB:
Changing storage engines has significant performance impact. Contact us if you are using a different storage engine on your source database and cannot change it prior to migrating.

​
Foreign key import issues

​
Import slower than expected

Foreign key imports use an atomic copy (--atomic-copy), which holds a long-running transaction on your source database. This can be slow on large databases. Solution: Run the import during off-peak hours, and make sure your source database has enough CPU and I/O headroom for the copy.

​
Import failed and won’t resume

Unlike regular imports, foreign key imports must start from the beginning if they fail. Solution: Before retrying:
  1. Fix any errors that caused the failure
  2. Make sure your binlog retention is long enough for the full import
  3. Consider importing during off-peak hours
To retry, cancel the workflow with --keep-data=false and create it again.

​
Can’t select specific tables

When your database has foreign keys, import every table with --all-tables to maintain referential integrity. If you really only need specific tables, you’ll need to:
  1. Remove foreign key constraints from your source database
  2. Import only the tables you need
  3. Recreate foreign key constraints in PlanetScale after import
Note: We recommend importing all tables to avoid referential integrity issues.

​
Schema errors when creating the external keyspace

​
External keyspace created with schema errors

Schema errors, such as a table without a unique key, are listed for each table but don’t stop the external keyspace from being created. Tables with schema errors will fail to import. Solution:
  • Fix the tables on your source database, then run create-external --dry-run again to confirm, or
  • Leave those tables out of the import with --exclude-tables when you create the MoveTables workflow
Server configuration and user grant errors always need to be fixed first, because PlanetScale won’t create the external keyspace until they pass.

​
Import monitoring issues

​
Replication lag is high

During the initial copy phase, high replication lag is normal. The lag should drop once the copy finishes. If lag stays high after copy completes:
  1. Check source database load - High write activity on source can cause lag
  2. Slow queries - Look for slow queries or locks on the source database
  3. Network issues - Check for network latency between source and PlanetScale
  4. Large transactions - Very large transactions take time to replicate
Solutions:
  • Reduce write load on source during import
  • Wait for off-peak hours
  • Check binlog retention isn’t expiring before lag catches up

​
Workflow stopped after a schema change

With the default --on-ddl STOP, the workflow stops when a schema change runs on your source database. The stream’s message starts with Stopped at DDL. Solution: Review the schema change, apply it to your PlanetScale database if needed, then resume the workflow with pscale branch vtctl move-tables start.

​
Streams show errors

Check the message on each stream in the status output, or the Streams panel on the workflow page in the dashboard. Common ones: “Access denied” - Permission issues. See user requirements. “Table doesn’t exist” - Schema may have changed during import. Don’t modify schema during import. “Deadlock found” - Usually temporary. The import will retry. Connection lost - Network issue or source database restarted. The import will retry.

​
Import stuck in “Copying” phase

The copy phase can take a while for large databases. Check:
  • Check table_copy_state in the status output, or the Tables panel on the workflow page, to see if it’s actually stuck or just slow
  • Check the stream messages for any errors
  • Verify source database is responding
If truly stuck:
  1. Check source database for locks or slow queries
  2. Verify network connectivity
  3. Look for errors in the stream messages

​
Permission errors

​
MySQL error 1045: Access denied

Error: Access denied for user 'migration_user'@'%' Solution: Check that your migration user has all required permissions. See our import user permissions. For foreign key imports, the user needs either:
  • FLUSH_TABLES or RELOAD privileges (preferred)
  • LOCK TABLES privilege (minimum)
Verify grants:

​
Required grants are missing

Error: external database does not have the required user grants: required privileges [...] are not present Solution: Grant the privileges listed in the error. They must be granted directly to the user at the global or database level. See Import user permissions. If the error says the permissions do not match user, the user was created for a specific host. Create it for the host '%' instead.

​
Can’t create the ps_import database

Solution: Grant the migration user permissions on the database PlanetScale creates to track replication:

​
Traffic switching issues

​
Can’t switch replica traffic

Make sure:
  • Replication lag is low (under a few seconds). switch-traffic fails if lag is above --max-replication-lag-allowed
  • Every stream is Running
  • No stream shows an error

​
Can’t switch primary traffic

Make sure:
  • Your application is connected to PlanetScale
  • Replication lag is minimal
  • Every stream is Running

​
Data inconsistency after switching

If you notice missing or stale data after switching traffic:
  1. Check replication lag - it may still be catching up
  2. Verify your application is actually connecting to PlanetScale
  3. Run a VDiff to compare your source database with PlanetScale
Don’t complete the import until you’ve verified data consistency.

​
Completing the import

​
Complete fails with keep_data must be true

Error: keep_data must be true when the source keyspace is external Solution: Completing an import never removes tables from your source database. Pass --keep-data=true, with an =, and leave out --rename-tables.

​
Common provider-specific issues

​
AWS RDS

Problem: Can’t modify GTID settings on default parameter group Solution: Create a custom DB parameter group with your MySQL version, modify settings there, then apply to your database. Problem: Binary logs not enabled Solution: Enable automated backups with retention >= 2 days.

​
Azure

Problem: Can’t set gtid_mode directly to ON Solution: Change through intermediate states: OFF_PERMISSIVE → ON_PERMISSIVE → ON

​
DigitalOcean

Problem: ANSI_QUOTES mode enabled Solution: Remove ANSI_QUOTES from Global SQL mode in Settings. Problem: Binlog retention too short Solution: Set Binlog Retention Period to at least 172800 seconds (48 hours).

​
GCP Cloud SQL

Problem: Binary logging disabled Solution: Enable Point in Time Recovery (PITR) from the GCP console.

​
Still stuck?

If you’ve tried the solutions above and are still having issues:
  1. Check your database’s error logs
  2. Review our general MySQL compatibility guide
  3. Look at the specific provider guide for your database
  4. Check the status output or the workflow page in the dashboard for detailed error messages
  5. Contact PlanetScale support

​
Need help?

Get help from the PlanetScale Support team, or join our Discord community to see how others are using PlanetScale.