Troubleshooting
Migrations package issues and fixes.
Migration Issues
Migration not running
Problem: migrate says nothing to run, but table missing.
Cause: Migration already marked as run, or file not found.
Fix: Check version tracking:
// Check which migrations have been recorded as run
$ran = get_option($context->optionKey('migrations'), []);
print_r($ran);
dbDelta creates wrong columns
Problem: Column types or defaults wrong after migration.
Cause: dbDelta has strict formatting requirements.
Fix: Follow dbDelta rules:
// Bad: Wrong formatting
$sql = "CREATE TABLE {$table}(
id INT PRIMARY KEY AUTO_INCREMENT
)";
// Good: Correct formatting
$sql = "CREATE TABLE {$table} (
id bigint(20) unsigned NOT NULL AUTO_INCREMENT,
PRIMARY KEY (id)
) {$this->charsetCollate()};";
// Note: Two spaces before (id) in PRIMARY KEY
Foreign keys not created
Problem: Foreign key constraints missing.
Cause: dbDelta doesn't support foreign keys.
Fix: Add constraints separately:
public function up(): void
{
$this->runDbDelta($createTableSql);
// Add FK manually
global $wpdb;
$wpdb->query("ALTER TABLE {$this->table} ADD CONSTRAINT ...");
}
Multisite Issues
Migrations run on wrong site
Problem: On multisite, tables created on main site only.
Cause: Using site scope when network needed.
Fix: Use correct table scope:
// For network-wide tables
$table = $context->tableName('settings', 'network');
// For per-site tables
$table = $context->tableName('orders', 'site');
Version tracking per-site
Problem: Migration version shared across sites.
Cause: Using non-prefixed option key.
Fix: Use context-prefixed option:
$key = $context->optionKey('migrations');
// Each site gets its own prefixed option key