Troubleshooting Flywheel Migrations Plugin

In this help doc, we’ll walk you through troubleshooting the most common issues when using the Flywheel Migrations plugin.

Table of Contents:

1. Running into an issue kicking off the migration?
2. Oh no! Something went wrong with your migration!
3. Post-Migration

Running into an issue kicking off the migration?

Unable to access wpconfig file error message

This error message pops up for a handful of reasons, but the most common reason stems from incorrectly filling out the migration details. Take a look at this guide on how to migrate your site with the Flywheel Migrations plugin to ensure those details are correct! Be sure to check for unwanted spaces, extra characters, or typos. Here’s what your form should look like when filled out.

Just created your Flywheel destination site? We see some users experience this error when trying to migrate their site to a freshly spun-up Flywheel site. The Flywheel Migrations plugin uses your SFTP credentials (the same as your Flywheel login) to migrate the site. If you’ve recently created the destination site on Flywheel, you may be running into SFTP cache. We recommend waiting 10-15 minutes before trying again.

Locally developed sites

Unfortunately, the Flywheel Migrations plugin does not support migrations from locally developed sites. If you are using Local, you can push your site’s content to Flywheel using Local Connect! If you’re using another tool to develop your site locally, we recommend creating an export of the site’s wp-content and database to manually migrate your site or submit a migration request.

Destination site inaccessible

The Flywheel Migrations plugin will not kick off if the source and/or destination site is inaccessible. If the source site is inaccessible, we recommend reaching out to your current hosting provider to address it. If the Flywheel destination site is showing an “Oops” page or a critical error, reach out to our 24/7 support team.

Oh no! Something went wrong with your migration!

Migration Logs

Once a migration finishes (regardless of its status), a JSON-formatted log file can be found within your Flywheel destination site in the `_fly-private` directory. These log files provide handy information like start and end time, the total number of files moved, and status codes. These status codes are helpful for troubleshooting migration failures, and below are a few of the most common reasons we see. More information on migration logs can be found in this overview guide on Migrations.

Migration Failure Reasons

Using the migration logs, you can find the status code for the migration, which often includes messages like the following:

Connection Issues:

If your migration fails due to a connection issue, you may see a status message like the following in the logs:

• We are having trouble reaching the destination site. You can contact your host to validate if there has been any change to your hosting account.
• Incorrect folder selected. Mysupercoolsite.flywheelsites.com is not being served from the folder: /flywheel/mysupercoolsite

Any error messages that specify the source site would mean there may be something happening on the original site you are trying to migrate. We recommend getting in touch with your current host provider to help troubleshoot those issues!

Any error message that specifies the destination site means there may be something going on with the Flywheel site you are migrating to. If any changes have been made to the primary domain, DNS, or settings in your Flywheel site’s dashboard, it is likely those changes interfered with the migration. We recommend trying the migration one more time. Typically, we see users have success after a second attempt. Otherwise, hit up our Onboarding team!

Database Import Issues:

If the migration fails because of the site’s database, you may see a status message like the following in the logs:

• Database connection failed. Please check the database username/password/hostname.
• Error while creating the table `insert_table_name_here`. Table name is too long.

The plugin moves the site’s files first and the database follows. Typically when an error like this comes up, it means the migration of the files themselves succeeded, but you will need to manually import the database.

To do so, you’ll want to obtain a copy of your database and start on step 4 of this manual migration guide. If you’d like some help, reach out to our Onboarding team for assistance with this.

Generic Failure Message:

Some error messages found in the logs are a bit more general. You may see messages like:

• An error occurred while syncing your site. Please contact support team.
• Not able to connect to server. Please retry after some time.
• Unable to execute PHP file on the site. Please check with your hosting provider.
• The operation could not be completed. The file/directory is not present.

Unfortunately, these errors do require some investigation to figure out the source. Our recommended resolution for these types of errors is to use another migration method (whether it be a manual migration or another plugin) or submit a migration request. If you run into this on multiple sites, please reach out to our Onboarding team!

Post-Migration

If you’re running into issues on the migrated site after the migration completes, we recommend checking out the following guides:

• A Guide to Clearing Your Plugin/Theme Caches
• Critical Error/White screen/500 Error
• More Post-Migration Troubleshooting