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.

Drupal Issues

Multiple site directories found within the import archive

Cause: The migration tool found a multisite installation, which is not supported on the platform.

Solution: Refer to Extracting Sites from a Drupal Multisite.

Drush archive missing code or files

Cause: If you have an existing archive (.tgz) file in sites/default/files, the drush ard command may generate an archive without all expected components.

Solution: Delete all archives and try running drush ard again.

HTTP 404 error: Unable to download the archive

Solution: Go the to files directory of your existing site and check if the site archive was generated successfully. If you're hosting the archive on a third party like Dropbox or Google Drive, confirm that it was uploaded successfully. Visiting the archive link with a browser should download the files automatically. You may need to run the drush ard command again if you can't find the site archive.

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 Drupal sites should include index.php at the code root level, along with the following directories:

├── includes
├── index.php
├── misc
├── modules
├── profiles
├── scripts
├── sites
    └── all
        ├── modules
        └── themes
    └── default
        └── settings.php
└── themes

Multiple file directories found within the import archive

Cause: The migration tool found more than one potential location for files within the archive. This error also occurs if Drupal's private files directory is not placed within the public directory: sites/default/files/private.

Solution: All files must be moved into /sites/default/files. For more details, see Files and Symlinks and Assumed Write Access.

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.