Information for: DEVELOPERS   PARTNERS   SUPPORT

Troubleshooting migrations with Acquia Migrate Accelerate

My migration environment failed to get created successfully

There are several reasons why your migration environment might initially fail. Check for error messages in the task log in the Acquia Cloud Platform UI, or go through the following checklist:

  1. In your sites.php file, ensure that the default domain name of your source environment is configured to use the site directory that you wish to migrate. For more information, see I want to change the source database for my migration. If your sites.php file is configured incorrectly, you might see an error message similar the following:

    Generating recommendations failed. If you have a docroot/sites/sites.php file, please make sure that the internal
    Acquia domain https://EXAMPLE.prod.acquia-sites.com/ is configured to point to the docroot/sites/ subdirectory that
    you wish to migrate. See the documentation for details.
    
  2. Some modules on Drupal.org claim to be compatible with Drupal 9. However, they actually cause issues when you install them in Drupal 9. The migration environment fails when one of these modules is installed. Acquia constantly monitors these modules, but new releases happen all the time. It’s possible that you’ve run into a recent regression. File a support ticket so that Acquia can block the module and help you move forward. You might see an issue similar the following:

    Your requirements could not be resolved to an installable set of packages.
    
  3. Check to ensure that your repository has a “welcome” tag. If you’ve removed it previously, you can recreate a dummy “welcome” tag (it can be empty with just a text file), and then the environment creation process should work as expected.

  4. Check to ensure that you’re following Drupal and Acqiua best practices for Setting the private file directory on Acquia Cloud. If your site’s private file directory does not follow these best practices, it may cause issues.

I have some issues to resolve on my messages tab. What is the best way to handle them?

The messages tab includes two types of messages that should be addressed differently:

  • Migration issues: these typically need to be fixed on the D9 site after your migration. However, some of these issues may be solved by making changes on the D7 site. For most of these issues, Acquia Migrate Accelerate automatically provides a suggested solution. If it does not, create a support ticket.
  • Entity validation errors: these are virtually always data integrity errors on your D7 site, and must be fixed there. For example, after the content of a particular type was already created, a new required field was added. The content that was already created never had this required field filled in. You need to click Refresh in the Acquia Cloud UI after making these changes. They then appear in the migration environment and the validation errors disappear after importing the refreshed data.

I want to use Acquia Migrate Accelerate to migrate a D7 multi-site

Acquia Migrate Accelerate does not officially support multisite migrations. However, you can migrate one site at a time by changing the default database. Follow the steps in the section I want to change the source database for my migration to change the source database for your migration to do so.

I want to change the source database for my migration

Note

This is only necessary for sites that currently are or once were multisite. If it’s a former multisite, Acquia recommends that you clean up your codebase and delete the sites.php file.

Set up your internal Acquia FQDN to point to the same site as the one you want to migrate by doing the following:

  1. In your sites.php file, ensure that the default domain name of your source environment is configured to use the site directory that you want to migrate. So, a line similar to the following is used if the multisite you want to migrate resides in docroot/sites/foobar:

    $sites['EXAMPLE.prod.acquia-sites.com] = 'foobar';
    

If there’s only one site directory, Acquia Migrate Accelerate uses that one. Otherwise, it uses the default.

If there’s more than one site directory and no default is specified, it fails with an error message similar the following:

Generating recommendations failed. If you have a ``docroot/sites/sites.php`` file, please make sure that the internal Acquia domain
https://EXAMPLE.prod.acquia-sites.com/ is configured to point to the ``docroot/sites/`` subdirectory that you wish to migrate. See
the documentation for details.

I have custom modules that I want to move to my D9 site

Acquia Migrate Accelerate cannot migrate custom modules. However, you can port the module to Drupal 9 and then add the module to the git branch that you’re using for the AMA environment. Preferably using composer require companyname/modulename, to make it easy to version the module independently of the migration environment, if it needs to be recreated.

I have a content type that cannot be migrated due to dependencies, but I cannot migrate the dependencies

If you do not see specific dependencies on the In Progress tab, check to see if you skipped them. If so, they appear on the Skipped tab. You must unskip them to add them back to the Migrations tab so that you can take action.

skippedtab

In other cases, there may be issues with the dependent migrations that you need to address before they can be successfully migrated. Click the module name to view the messages specifically related to that migration.

In some cases, you may have circular dependencies in your data model that prevent you from moving forward. In such a case, file a support ticket. You must provide a sanitized copy of your database so that the Acquia Support team can reproduce and troubleshoot your issue.

I want to start over, or need to recreate my migration environment

If you’ve encountered issues where using a new migration environment is the best course of action, you may need to destroy your existing environment and create a new one. Look for the trash can icon in the upper right corner of the migration environment.

startover

When you create the new migration environment, you will get the latest version of the AMA module, the latest version of the Recommendations Engine will be applied to your Drupal 7 site, you’ll install a fresh D9 environment, and re-import the latest content from your D7 production site.

Before doing that, ensure that all of your code changes are committed to the Git branch that your AMA environment is using. The Git branch name is indicated on the AMA environment card, and starts with “ama-“.

migrategitbranch

The new migration environment creates a new branch that does not include any of the work you did on your theme, your custom code, or any additional configuration changes that you made previously. Incorporate the work that you’ve already done by merging all the feature branches you were working on, or by cherry picking the changes and adding them to the new branch. If you are porting custom modules or themes, Acquia recommends to version each module or theme individually so that you can use the composer require companyname/modulename command for each of them in your new migration environment. That is simpler than moving over the work from the previous AMA branch.

If you need help with Git, see Resources for Learning Git in Acquia Knowledge Base.

I need to update the AMA module, but I don’t want to recreate my migration environment

For the AMA module, if there are new features or fixes that you need for your migration, you may be instructed to update to the latest version of the AMA module.

You do not need to start over with a new migration environment to take advantage of the latest features and fixes in the AMA module. Instead, run the following command on localhost or a Cloud IDE:

composer update acquia/acquia-migrate-accelerate --with-dependencies

Commit the result to Git. However, if you need to take advantage of features and fixes to the migrations recommendations or migration processing, you will need to recreate your migration environment.

I refreshed my database, but there is more data in the Refresh tab than I expected

With AMA’s Refresh function, you can copy over the live production database and file from your Drupal 7 site to the migration environment. After refreshing, you may see more content on the Refresh tab than what was changed. AMA is built upon Drupal’s migration system, which is unable to isolate the specific rows that were changed, so identifying the specific content types that were changed is definitely out of reach. The migration system knows which tables are changed, and so AMA identifies all of the migrations that rely on those tables as items to refresh.

For example, if a single node (an article, page, or blog) was created, the migration system does not know which of those types of content needs to be refreshed. Therefore, AMA marks them all as needing a refresh, and all appear on the Refresh tab.

The composer.json file that was generated by the Acquia Migrate Accelerate module is restricting the version of modules so they can’t be updated. How do I update them?

Yes, the AMA-generated composer.json is restricting versions of just about every module, for two reasons:

  • It’s pinning to a specific version, such as 1.4, if one or more patches, which add or fix migrations, are applied. That’s because the patches may not apply to newer versions.
  • It’s specifying a particular minimum version, such as ^2.3, to ensure that a version of the module is installed that contains a migration path that Acquia has vetted. This is particularly true for Drupal core, where for the past year, AMA has been applying between 30 and 50 patches to it for you, to make the migration work reliably. Acquia is always working to get those patches committed upstream.

After the migration is complete

After the migration is complete, you uninstall the acquia_migrate, migrate_drupal, and migrate modules. After that, there is no more need for patches that add or fix migrations. At this point, you can remove the patches and also make all of the version constraints less restrictive. For example, AMA currently recommends drupal/user_hash 2.0.0 with this patch:

"require": {
     …
     "drupal/user_hash": "2.0.0",
     …
 },
 "extra": {
     …
     "patches": {
         …
         "drupal/user_hash": {
             "Issue #3232037: Configuration missing while D7 to D9 migration": "https://www.drupal.org/files/issues/2021-09-09/configuration_missing-3232037-2.patch"
         },
         …
     },
     …

If you delete that patch, you end up with:

"patches": {
     …
 }

then you can also loosen the version constraint, which means you end up with:

"require": {
     …
     "drupal/user_hash": "^2",
     …
 },
 "extra": {
     …
     "patches": {
         …
     },
     …

Now, run composer install to see:

$ composer update drupal/user_hash
Gathering patches for root package.
Loading composer repositories with package information
Updating dependencies
Lock file operations: 0 installs, 1 update, 0 removals
  - Upgrading drupal/user_hash (2.0.0 => 2.0.1)
Writing lock file
Installing dependencies from lock file (including require-dev)
Package operations: 0 installs, 1 update, 0 removals
  - Downloading drupal/user_hash (2.0.1)
Gathering patches for root package.
Gathering patches for dependencies. This might take a minute.
  - Upgrading drupal/user_hash (2.0.0 => 2.0.1): Extracting archive
   Generating autoload files
43 packages you are using are looking for funding.
Use the `composer fund` command to find out more!

In this example, composer found the newest version matching the constraint ^2. You’ll have to repeat this process for every package that has a specific version pinned. Composer unfortunately makes this hard to automate. Besides, you’ll want to do this gradually to ensure everything continues to work. You may have added patches of your own, which you do not want to remove.

I need to provide a “sanitized database” to the AMA team so they can troubleshoot an issue - how do I do that?

Every Drupal site is different, and so is every Drupal 7 to 9 migration. Your migration might run into an issue that Acquia Migrate Accelerate has not seen before. When this happens, the AMA team requests a “sanitized database” from your Drupal 7 site so that they can reproduce the issue and develop a resolution that will help you move forward, and ensure that others do not run into the same issue. The following are the instructions for creating a sanitized database on Acquia Cloud:

  1. Back up your development environment database.

  2. Copy your production database to your development environment.

  3. SSH into your application and run the following command to generate the sanitized database:

    drush sql-sanitize

  4. Share the file with Acquia’s Support team by attaching it to the support ticket.

  5. Restore the backed up database to your development environment.