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.
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
"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
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.
If you use Redis caching, disable it. On BOA, you do this by editing
sites/foo.com/modules/. Add (or edit) this line:
redis_cache_disable = TRUE
(Correct as of BOA-2.1.3.)
"Run Health Check" Task
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.
Credit card settings->
Encryption key directory
Set this directory to:
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.