# Migration Troubleshooting

> SiteVault Pro migration troubleshooting: fix import failures and timeouts, database compatibility errors, file permissions, and URL replacement problems.

- Canonical: <https://royalplugins.com/support/sitevault/migration-issues/>
- HTML version: <https://royalplugins.com/support/sitevault/migration-issues/>

---

Moving a WordPress site to a new host or domain can be tricky. This guide covers the most common migration issues and how to fix them.

### Always Create a Backup Before Migrating!

Before starting any migration, create a full backup of both the source and destination sites. This gives you a recovery point if something goes wrong.

## Migration Fails or Times Out

Large sites with many files can time out during migration package creation or import.

#### Package Creation Times Out

Symptom: "Migration package creation failed" or progress bar stops

##### Solutions:

- **Increase PHP limits** - Set `max_execution_time = 300` and `memory_limit = 512M` (see note below)
- **Exclude large folders** - Go to Settings and exclude cache directories, logs, or large media folders
- **Try database-only first** - Create a database-only migration package, then manually FTP the files
- **Use incremental** - Enable incremental backups to reduce package size (Pro)

Shared Hosting: Changing PHP Limits

On shared hosting, you usually can't edit php.ini directly. Try these alternatives:

- Add to `.htaccess`: `php_value max_execution_time 300`
- Create `.user.ini` in WordPress root with: `max_execution_time = 300`
- Use your hosting panel (cPanel > PHP Settings, or similar)
- Contact your host's support to increase limits

#### Import Fails on Destination

Symptom: Installer script shows error during database import or file extraction

##### Solutions:

- **Check disk space** - Ensure destination has at least 3x the package size available
- **Verify database credentials** - Double-check the database name, username, password, and host
- **Check database permissions** - User needs CREATE, DROP, INSERT, UPDATE, DELETE, ALTER permissions
- **Try importing manually** - Extract the package, import SQL via phpMyAdmin, upload files via FTP

Pro Tip: Use Push Migration

SiteVault Pro's push/pull migration handles large sites better with chunked transfers and automatic retry on failure.

## White Screen After Migration

A white screen (WSOD) after migration usually indicates a PHP error or database connection issue.

#### Step-by-Step Diagnosis Common Fix

#### Enable Debug Mode

Edit wp-config.php on the destination site and add:

```
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', true);
```

#### Check Error Messages

Refresh the page to see the actual error, or check wp-content/debug.log

#### Common Fixes Based on Error

See below for solutions to specific error messages

#### "Error establishing database connection"

The database credentials in wp-config.php don't match the new server

##### Fix:

- Open wp-config.php
- Update `DB_NAME`, `DB_USER`, `DB_PASSWORD`, and `DB_HOST` to match your new hosting
- On many hosts, DB\_HOST is `localhost` but some use IP addresses or custom hostnames

#### "Fatal error: Class not found" or "require\_once() failed"

Files weren't uploaded correctly or file paths are wrong

##### Fix:

- Re-upload all files from the migration package
- Check file permissions (folders: 755, files: 644)
- Verify no files were skipped during FTP upload

#### "Parse error" or "Syntax error"

PHP version mismatch between servers

##### Fix:

- Check the PHP version on your old host
- Match it on the new host (or upgrade to PHP 8.0+)
- Contact your new host to change PHP version in hosting panel

## URL Replacement Issues

After migration, URLs may still point to the old domain, causing broken links or redirect loops.

#### Site Redirects to Old Domain

Visiting new domain redirects to old domain, or infinite redirect loop

##### Solutions:

1. **Check wp-config.php** - Add these lines before "That's all, stop editing!":

```
define('WP_HOME', 'https://newdomain.com');
define('WP_SITEURL', 'https://newdomain.com');
```

If that doesn't work, also update the database directly:

```
-- Run in phpMyAdmin
UPDATE wp_options SET option_value = 'https://newdomain.com'
WHERE option_name = 'siteurl';

UPDATE wp_options SET option_value = 'https://newdomain.com'
WHERE option_name = 'home';
```

#### Images and Links Point to Old Domain

Site loads but images are broken, internal links go to old domain

##### Solutions:

- **Run search-replace** - SiteVault Pro includes automatic URL replacement during migration
- **Use WP-CLI** - If you have SSH/command line access:

```
wp search-replace 'https://olddomain.com' 'https://newdomain.com' --all-tables-with-prefix
```

Shared Hosting: No CLI Access?

Most shared hosts don't provide SSH access. Use the free **"Better Search Replace"** plugin instead - it handles serialized data safely and works entirely through the WordPress admin.

Serialized Data

Simple find-replace in phpMyAdmin will break serialized data in WordPress options. Always use a tool that handles serialization (SiteVault, WP-CLI, or Better Search Replace).

#### Mixed Content Warnings (HTTP/HTTPS)

Browser shows "Not Secure" or blocks some content

##### Solutions:

- Run search-replace from `http://` to `https://`
- Check theme/plugin settings for hardcoded URLs
- Add this to .htaccess to force HTTPS:

```
RewriteEngine On
RewriteCond %{HTTPS} off
RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]
```

## File Permission Issues

Incorrect file permissions can cause uploads to fail, plugins to break, or security warnings.

#### Can't Upload Images or Install Plugins

"Unable to create directory" or "Upload failed" errors

##### Fix file permissions:

- **Folders** should be `755` (rwxr-xr-x)
- **Files** should be `644` (rw-r--r--)
- **wp-config.php** should be `600` or `640`

##### Method 1: Via FTP Client (Recommended for Shared Hosting)

1. Connect to your site with FileZilla, Cyberduck, or similar FTP client
2. Select the folders/files you need to fix
3. Right-click and choose "File Permissions" (or similar)
4. Enter 755 for folders, 644 for files
5. Check "Recurse into subdirectories" if available

##### Method 2: Via SSH (VPS/Dedicated Servers)

```
# Fix folder permissions
sudo find /path/to/wordpress -type d -exec chmod 755 {} \;

# Fix file permissions
sudo find /path/to/wordpress -type f -exec chmod 644 {} \;

# Secure wp-config.php
sudo chmod 600 /path/to/wordpress/wp-config.php
```

#### File Ownership Wrong

Permissions look correct but uploads still fail

##### Fix:

Files may be owned by the wrong user. This is common after FTP uploads.

Shared Hosting

On shared hosting, you typically cannot change file ownership yourself. Contact your host's support and ask them to fix ownership on your WordPress directory. They can run the appropriate chown command for you.

**VPS/Dedicated servers:** Run via SSH:

```
sudo chown -R www-data:www-data /path/to/wordpress
```

(Replace `www-data` with your server's web user - may be `apache`, `nginx`, or your cPanel username)

## Push/Pull Migration IssuesPRO

Direct server-to-server migration troubleshooting.

### How Push Migration Works

Push migration transfers your site directly between servers using chunked uploads:

1. **Source site** (old server) creates migration package and pushes to destination
2. **Destination site** (new server) receives chunks and assembles the package
3. Uses chunked uploads to handle large sites without timeout issues

#### Setting Up Push Migration

##### On Destination (new server):

1. Install WordPress + SiteVault Pro
2. Go to **SiteVault → Migration**
3. Find the **Pull Migration** section
4. Copy the **Secret Key** (auto-generated 32-char string)

##### On Source (old server):

1. Go to **SiteVault → Migration**
2. Find the **Push Migration** section
3. Enter:
   - **Destination URL:** `https://newsite.com`
   - **Secret Key:** (paste from destination)
4. Click **Push to Remote**

Security Note

The secret key is stored in `wp_options` as `rb_pull_secret_key`. Regenerate it after migration: SiteVault → Migration → Click "Regenerate". Push migration requires the destination site to be publicly accessible.

#### Can't Connect to Remote Site

"Connection failed" or "Invalid response from remote site"

##### Checklist:

- SiteVault Pro is installed and activated on BOTH sites
- Secret key is entered correctly (check for extra spaces)
- Remote site is accessible via HTTPS
- Firewall isn't blocking the connection
- REST API is not disabled on remote site

#### "Chunk X Failed" Error

Migration fails partway through with chunk upload errors

##### Cause:

Permission issues on destination server - PHP can't write to temp directory.

##### Solution (VPS/Dedicated Servers):

```
# Fix ownership of SiteVault directories
sudo chown -R www-data:www-data /var/www/site/wp-content/uploads/sitevault
sudo chmod -R 775 /var/www/site/wp-content/uploads/sitevault
```

**Key directories that need write access:**

- `wp-content/uploads/sitevault/temp/` - chunk assembly
- `wp-content/uploads/sitevault/backups/` - final packages

Shared Hosting

On shared hosting, contact your host's support and ask them to fix permissions on your `wp-content/uploads/sitevault/` directory. They can run the appropriate chown command for you.

#### Transfer Stalls or Fails

Progress shows but never completes

##### Possible Causes:

- Shared hosting outbound firewall restrictions
- PHP timeout on source server
- Large chunks timing out

##### Solutions:

- Check server timeout settings (increase to 300+ seconds)
- Check source server's `max_execution_time`
- Disable any caching plugins temporarily
- Try during off-peak hours when server load is lower
- If package is very large, use manual migration with FTP instead

#### Database Prefix Mismatch

Source site has different table prefix than destination (e.g., `vIP_` vs `wp_`)

##### Solution:

After downloading the SQL file, run search-replace before importing:

```
# Replace old prefix with new prefix
sed -i "s/oldprefix_/wp_/g" database.sql

# Then import
mysql database_name < database.sql
```

## Manual Migration Fallback

If push migration fails partway through, you can often recover manually from the partially transferred files.

#### Recovering from Failed Push Advanced

##### Step 1: Check What Was Transferred

```
ls -la wp-content/uploads/sitevault/temp/import-*/
```

Typically contains:

- `database.sql` - Full database dump
- `plugins/` - All plugins
- `themes/` - All themes
- `uploads/` - Media files
- `manifest.json` - Package metadata

##### Step 2: Manual Restore

```
# Copy files
cp -r import-*/plugins/* wp-content/plugins/
cp -r import-*/themes/* wp-content/themes/
cp -r import-*/uploads/* wp-content/uploads/

# Fix permissions
sudo chown -R www-data:www-data wp-content/

# Import database (fix prefix if needed)
sed -i "s/OLD_PREFIX_/wp_/g" import-*/database.sql
mysql database_name < import-*/database.sql

# Update site URLs
wp option update siteurl "https://newsite.com"
wp option update home "https://newsite.com"
```

##### Step 3: Activate Plugins

```
# Activate WooCommerce first (themes may depend on it)
wp plugin activate woocommerce

# Then activate the rest
wp plugin activate --all
```

## Pre-Migration Checklist

Complete these steps before starting any migration to ensure a smooth process.

#### On Source Server (Before Migration)

- ☐
  Disable security plugins that send email alerts (prevents email flood)
- ☐
  Note current plugin list and versions
- ☐
  Verify database prefix (`wp-config.php` → `$table_prefix`)
- ☐
  Have cPanel/FTP access as backup

#### On Destination Server (Before Migration)

- ☐
  Fresh WordPress installed
- ☐
  SiteVault Pro installed and activated
- ☐
  `wp-content/uploads/` writable by web server
- ☐
  PHP memory limit ≥ 256M
- ☐
  PHP max\_execution\_time ≥ 300

## WooCommerce Migration Notes

WooCommerce sites require special attention during migration due to theme and plugin dependencies.

#### Theme Activation Order

Problem: Theme crashes with "Call to undefined function is\_checkout()" or similar

If your theme uses WooCommerce functions (like `is_checkout()`), you must activate WooCommerce BEFORE the theme:

```
# Reset theme to default first (use whichever default is installed)
wp theme activate twentytwentyfour

# Activate WooCommerce
wp plugin activate woocommerce

# Now activate your WooCommerce theme
wp theme activate your-woo-theme
```

Important

If you're on shared hosting without WP-CLI access, do this via FTP: rename your theme folder temporarily, activate WooCommerce in wp-admin, then rename the theme folder back.

#### Verify Data After Migration

After migrating a WooCommerce site, verify your critical data:

```
# Check product count
wp post list --post_type=product --format=count

# Check orders
wp post list --post_type=shop_order --format=count
```

Also check in wp-admin:

- Products → All Products (verify count matches)
- WooCommerce → Orders (verify orders exist)
- WooCommerce → Settings → Payments (reconfigure if needed)
- Test checkout process with a test order

## Troubleshooting Commands

Useful commands for diagnosing migration issues (requires SSH access).

#### Server Diagnostics Advanced

```
# Check PHP errors (Nginx)
tail -f /var/log/nginx/error.log

# Check PHP errors (Apache)
tail -f /var/log/apache2/error.log

# Test site access
curl -I https://site.com/

# List active plugins
wp plugin list --status=active

# Check database tables count
wp db tables | wc -l

# Search-replace URLs in database (dry run first)
wp search-replace 'https://oldsite.com' 'https://newsite.com' --all-tables-with-prefix --dry-run

# Then run for real
wp search-replace 'https://oldsite.com' 'https://newsite.com' --all-tables-with-prefix
```

Shared Hosting Alternative

If you don't have SSH access, most of these can be done through wp-admin or phpMyAdmin. Use the "Better Search Replace" plugin for URL replacement.

## Post-Migration Checklist

After a successful migration, verify everything is working:

- Homepage loads correctly
- Admin login works
- All pages and posts are accessible
- Images display properly
- Forms submit successfully
- E-commerce checkout works (if applicable)
- SSL certificate is active (green padlock)
- Permalinks are working (Settings > Permalinks > Save)
- Search functionality works
- Contact forms send emails

Flush Permalinks

After migration, go to Settings > Permalinks and click Save Changes (without changing anything). This regenerates .htaccess and fixes many 404 errors.

Update DNS

If you're changing hosts, update your domain's DNS to point to the new server. DNS propagation can take up to 48 hours worldwide.

## Still Need Help?

If you're still having trouble with your migration:

- Check the WordPress error log: `wp-content/debug.log`
- Check server error logs in your hosting control panel
- Try a manual migration: export database, FTP files, import database, run search-replace

Still stuck? Email priority support

Email **[support@royalplugins.com](mailto:support@royalplugins.com)** with your source site URL, destination site URL, SiteVault version, and the migration error you’re seeing. Priority email support is included with your SiteVault Pro license — typical response time is within 24 hours.

[Back to SiteVault Docs](https://royalplugins.com/support/sitevault/)
[Staging Troubleshooting](https://royalplugins.com/support/sitevault/staging-issues/)