1. Technology
You can opt-out at any time. Please refer to our privacy policy for contact information.

Aegir "Migrate" Task Fails on Drupal Major Upgrade

How to Troubleshoot an Aegir Failure and Upgrade Your Drupal Site



When you use Aegir to manage your Drupal sites, you expect to upgrade these sites by migrating between Aegir "platforms". In theory, Aegir can handle even a dreaded major upgrade with ease. (For example, you can migrate your site from a Drupal 6 platform to a Drupal 7 platform.) But if that "Migrate" task fails for a major upgrade, you'll need to dig in and do some tweaking. Here are some troubleshooting steps to try.

Some of these steps are taken from the longer steps you would take to upgrade a Drupal site manually if you weren't using Aegir. They are not exhaustive, but they may be enough to fix your migration.

Examine the Log of the Failed Migrate Task

Your first step is to scroll through the (copious) log for the failed Migrate task. In the Aegir admin, click View beside the failed task.

Error lines should be marked in red. As you skim them, see if any obvious solutions present themselves.

Disable (And Possibly Uninstall) Troublesome Modules

For instance, you may notice SQL or other errors that seem to refer to a specific module. Like this:


Base table or view not found: 1146 Table 'database_name.ckeditor_input_format' doesn't exist


The key here is "ckeditor". The CKEditor module is causing trouble. At a minimum, we'll need to disable this module, then verify the site.

(By comparison, in a standard Drupal upgrade, you should disable all contrib modules, then carefully turn them on again.)

Disabling may work, but it may not be enough, since this leaves the module's data (if any) in the database. In some cases, you must actually uninstall the module, clearing its data from the database, so that you can re-install the new version cleanly after the upgrade. (Read more on the difference between disabling and uninstalling a Drupal module.)

On the other hand, if you need this data, and you don't want to have to manually preserve it during the migration, you should try just disabling the module.

Whether you uninstall the disabled module before the migration or not, after the migration, the new version of this module will likely have database updates to run. Aegir will run database updates on all enabled modules as part of the migration, but if you disable any modules here, make sure to check for database updates manually after the migration.

To summarize:

  • Disable any modules that are mentioned in the error log.

  • If the Migrate task fails again, try uninstalling these modules. Check whether you need to manually preserve any data they have saved to the database. (For example, you could copy or rename the table, so that the uninstallation won't delete it.)

  • When you do get a successful migration, re-enable the disabled modules and run any database updates. You can visit /update.php or do drush dbup.

"Verify" Task Before Each Migration

When you are trying to debug a migration, make sure you run the Verify task on your site before each attempt to Migrate. This will tell Aegir about any changes you've made, such as disabling modules.

"Rebuild Registry" Task Before Each Migration

You should also rebuild the Drupal registry before each attempt to Migrate.

Disable Your Theme(s) and Switch to Garland

Your theme is a likely candidate for custom, version-specific code that will cause trouble during an upgrade. Disable it (and, if necessary, uninstall it).

Set the default theme to Garland. Garland is a stock theme that comes with Drupal and is guaranteed to work in the new version.

You set this theme with drush:

drush vset theme_default="garland"

If you have set other admin or maintenance themes, set these to Garland as well.

Disable Redis

If you use Redis caching, disable it. On BOA, you do this by editing boa_site_control.ini in sites/foo.com/modules/. Add (or edit) this line:

redis_cache_disable = TRUE

(Correct as of BOA-2.1.3.)

"Run Health Check" Task

The Run health check task can provide valuable information about what is breaking your Migrate task. Even if the health check "succeeds", you should click View and expand each section of the log. A successful health check doesn't mean all your migration problems are solved.

Ubercart Encryption Directory on BOA

If you're using an Ubercart platform on BOA, you may need a specific fix for the directory which stores the encryption keys.

  • Visit admin/store/settings/payment/edit/methods

  • Click to Credit card settings -> Encryption key directory

  • Set this directory to: ../keys.

Don't Give Up!

Wrestling with an Aegir migration can quail the stoutest among us, but don't give up. Enough tweaks, and that successful Migrate task will finally show in beautiful green.

Read more: What Is a Drupal "Major Upgrade"? | How Aegir Upgrades Your Drupal Site By Migrating Between Platforms

©2014 About.com. All rights reserved.