Troubleshooting

This section provides information on causes and solutions to error messages that display in the Site Dashboard if a migration fails to complete.

Before you Begin

1. Review Pantheon Platform Considerations if your code, database, and files have completed migrating, but your site is not working as you'd expect. For example, if your site uses PHP short tags, you'll need to convert them to standard PHP tags.

2. Check the log files to help identify and fix errors. The core is upgraded as part of the migration, so you may have additional work to complete the upgrade.

General Issues

Could not import database, unable to locate a database dump

Cause: The migration tool could not locate a MySQL database dump within the archive.

Solution: Ensure that the archive contains a valid MySQL database dump.

Multiple database dumps found within the import archive

Cause: The migration tool detected multiple MySQL database dumps within the archive.

Solution: Ensure that a single MySQL dump is included within the archive.

Multiple code roots found within the import archive

Cause: The migration tool detected more than one potential location for the code root in the archive.

Solution: Ensure that a single code root is included within the archive.

Destination Site Not Found Error

Cause: This error occurs when you are logged in with one identity and re-authenticate with a different account, or use Single Sign-On with Google. The site created will be associated with one account and the machine token with another.

Solution: Click your browser's back button from the Pantheon Dashboard and re-authenticate the user account for your current session.

Maximum Index Size

Cause: The MySQL reference manual explains this error as:

InnoDB has a maximum index length of 767 bytes for tables that use COMPACT or REDUNDANT row format, so for utf8mb3 or utf8mb4 columns, you can index a maximum of 255 or 191 characters, respectively. If you currently have utf8mb3 columns with indexes longer than 191 characters, you must index a smaller number of characters.

Sites migrated from hosts using utf8mb3 are upgraded to utf8mb4. If those sites have indexes larger than 191 characters, MySQL will return the following error on import:

Index column size too large. The maximum column size is 767 bytes

Solution: These tables will need to be updated. One method to update index length uses the ALTER TABLE command:

ALTER TABLE tableName DROP INDEX meta_key, ADD INDEX meta_key(meta_key(191));

This command can be used as part of a script to find and update large indexes.

Migration Fails

WP Engine blocks the Let's Encrypt challenge file, so you should schedule a maintenance window for HTTPS. If your migration fails, you can try the following workaround:

1. Create and download a backup point from WP Engine.

2. Unzip your site's backup point on your local machine.

3. Remove the WP Engine remnants. There are a few files you'll need to remove:

   • Drop-in plugins (e.g. wpengine-common) located at: \wp-content\mu-plugins

   • .gitattributes and .gitignore from the root folder

   • If object caching is enabled, remove the object-cache.php file located in /wp-content

4. Replace the existing wp-config.php with Pantheon's wp-config.php file. Preserve necessary logic from your existing file.

5. Move the mysql.sql database from the wp-content directory and place it in the project's root directory.

6. Follow the procedure to manually migrate your site.

WordPress Issues

CDN Blocking POST requests

Cause: This error can occur on sites using a content delivery network (CDN) service that is not configured to allow the POST HTTP method.

Solution: Temporarily set POST as an allowed HTTP method within the CDN's configuration and restart the migration process. The POST HTTP method can be disabled after the site has been successfully migrated.

Very Large Site Footprints

Cause: Imports can also fail for very large sites, which may time out while importing.

Solution: Restart the migration by going to the browser tab containing your WordPress dashboard, and click Migrate

Could not import code, the import file does not appear to contain a valid code directory.

Cause: The migration tool could not find the core files. This prevents the migration from completing because the site modules, plugins, and/or themes cannot be imported. This error also occurs when multiple settings.php files are present.

Solution: Check that the archive includes a valid code root with all core files. If multiple settings.php files are present, delete them from the archive. Archives for WordPress sites should include index.php at the code root level, along with the following directories:

├── index.php
├── wp-activate.php
├── wp-config.php
├── wp-comments-post.php
├── wp-blog-header.php
├── wp-admin
├── wp-cron.php
├── wp-load.php
├── wp-links-opml.php
├── wp-includes
├── xmlrpc.php
├── wp-trackback.php
├── wp-signup.php
├── wp-settings.php
├── wp-mail.php
├── wp-login.php
├── wp-content
    ├── index.php
    ├── mu-plugins
    ├── themes
    ├── plugins

Multiple file directories found within the import archive

Cause: The migration tool found more than one potential location for files within the archive.

Solution: All files must be moved into /wp-content/uploads. For more details, see Files and Symlinks and Assumed Write Access.