Developing migrations in Drupal is a powerful way to bring data from legacy systems into your modern site. However, many developers hit a frustrating roadblock: you add a new migration YAML file to your module, run drush migrate-status (drush ms), and the new migration is nowhere to be found. Even clearing the cache with drush cr doesn't seem to help.

In this guide, we will explore why Drupal migration configurations don't update automatically and provide several proven methods to refresh your migrations without the tedious process of uninstalling and reinstalling your custom module. Whether you are using the Migrate Plus module or core Migration plugins, these techniques will streamline your development workflow.

Why Drupal Doesn't See Your New Migrations

To solve the problem, we first need to understand how Drupal handles configuration. When you place a migration YAML file in your module's config/install directory, Drupal treats it as a Configuration Entity.

Configuration entities are only imported into the site's active configuration database during the initial installation of the module. Once the module is installed, Drupal stops looking at the config/install folder. This is why drush cr (rebuild cache) fails to pick up new files; the cache rebuild does not re-scan the filesystem for new configuration entities that haven't been "synced" yet.

Method 1: Partial Configuration Import (The Quick Fix)

If you are using the Migrate Plus module and your migrations are stored as configuration entities, the most direct way to force an update is to use a partial configuration import. This tells Drush to look at a specific directory and import the configuration files found there into the active store.

Run the following command, replacing the path with the actual path to your module:

drush config-import --partial --source=modules/custom/your_module_name/config/install/

This command is highly effective because it bypasses the full configuration sync process and targets only the files in your installation directory. After running this, your new migration should appear in the drush ms list immediately.

Method 2: Use Migration Plugins (The Modern Standard)

In earlier versions of Drupal 8, migrations were primarily configuration entities. However, a significant architectural shift occurred that turned migrations into Plugins.

If you move your migration YAML files from config/install to a directory named migrations in your module root, Drupal will treat them as plugins rather than configuration.

Directory Structure for Plugins:

your_module/
  ├── migrations/
  │   ├── cm_users.yml
  │   ├── cm_tags.yml
  │   └── cm_beers.yml
  └── your_module.info.yml

The Benefit: Unlike configuration entities, migration plugins are discovered via the plugin discovery system. When your migrations are plugins, a simple drush cr will work to refresh the list and pick up new files or changes to existing ones. This is the recommended approach for most modern Drupal projects (Drupal 9, 10, and 11).

Method 3: Using the Configuration Development Module

For developers who prefer to keep their migrations in config/install, the Configuration Development module is an essential tool. It allows you to specify which configuration files should be automatically re-imported every time you interact with the site.

First, install the module:

composer require drupal/config_devel
drush en config_devel

Then, add a config_devel section to your module's .info.yml file:

config_devel:
  install:
    - migrate_plus.migration.cm_beers
    - migrate_plus.migration.cm_users

You can then use the following Drush command to import a specific file:

drush config-devel-import-one (cdi1) modules/custom/your_module/config/install/migrate_plus.migration.cm_beers.yml

This is particularly useful during the iterative phase of writing migration mappings where you are frequently changing source fields or process plugins.

Method 4: The "Nuclear Option" (Reinstalling Modules)

If you are in an environment where you cannot install extra modules or the partial import is failing due to dependency issues, you may have to resort to reinstalling. However, you can automate this with Drush to save time. Note that this will delete any data associated with those modules, so use it with caution.

drush pmu your_module, migrate_tools, migrate_plus -y
drush en your_module, migrate_tools, migrate_plus -y

Best Practices for Migration Development

  1. Prefer Plugins over Config: Unless you need users to edit migrations through the Drupal UI, always place your YAMLs in the /migrations folder. It makes the development cycle much faster.
  2. Validate YAML Syntax: Often, a migration doesn't show up simply because of a syntax error (like an accidental tab instead of spaces). Use a YAML linter if a file refuses to import.
  3. Check Dependencies: If your migration cm_beers depends on cm_users, and cm_users hasn't been imported correctly, the second migration may not show up in the list.
  4. Version Compatibility: While these methods work for Drupal 8 through 11, the migration plugin system is the most stable and future-proof method for current versions.

Frequently Asked Questions

Why does drush cr not pick up my new migration YAML?

drush cr clears caches, but it does not re-scan the config/install directory for new configuration entities. It only scans for plugins. If your migration is in config/install, it is an entity; if it is in /migrations, it is a plugin.

Is there a difference between migrate_plus migrations and core migrations?

Yes. Core migrations are traditionally plugins. migrate_plus allows migrations to be treated as configuration entities, which enables features like migration groups and the ability to edit migrations via the UI. Most developers use migrate_plus for its extended functionality.

Can I convert a config-based migration to a plugin-based migration?

Yes. Simply move the file from config/install to the migrations directory and remove the uuid and langcode keys from the YAML file if they exist. Ensure your module doesn't have a strict dependency on the configuration entity existing in the database.

Wrapping Up

Refreshing migrations in Drupal doesn't have to involve the constant cycle of uninstalling and reinstalling modules. By understanding the difference between configuration entities and plugins, you can choose the workflow that best fits your project. For most developers, moving to the Migration Plugin system (using the /migrations folder) provides the smoothest experience, allowing drush cr to handle the heavy lifting. If you must stay with configuration entities, drush config-import --partial is your best friend.