fidzu : web

Your Current Platform	Migration Type	Primary Tooling
Drupal 7	Data + platform upgrade	Migrate API + Migrate Drupal
Drupal 9 / 10 / 11 (classic)	Layer adoption, no data move	Recipes + Canvas adoption
WordPress / Joomla / AEM / Sitecore	Full platform replacement	Migrate API + custom source plugins

Knowing which one you're doing early - before scoping or quoting - is the single biggest factor in accurate estimation.

---

The Migrate API: Your Foundation

Regardless of source platform, Drupal's Migrate API is the ETL (Extract-Transform-Load) engine underneath every non-trivial migration. It lives in Drupal core and is composed of three module layers:

• migrate - the core framework: source plugins, process plugins, destination plugins
• migrate_plus (contrib) - adds source types (JSON, XML, SOAP, HTTP), process plugin extras, and migration groups
• migrate_tools (contrib) - adds the Drush commands you'll use day-to-day

Install the contrib layer before anything else:

Image

A source plugin reads rows from legacy data. Process plugins transform field values one by one. The destination plugin writes to Drupal entities. Understanding this pipeline is what separates developers who debug migrations quickly from those who spend days chasing phantom errors.

---

Path 1: Drupal 7 → Drupal CMS 2.x

Drupal 7's end-of-community-life has passed, and commercial extended support windows are closing. If you're still running D7 in 2026, this migration is urgent - not optional.

Setup: Point the Migrate API at Your D7 Database

Add the legacy database as a second connection in settings.php:

Image

Image

Inspecting the Generated Migrations

The upgrade command generates a full set of migration YAML definitions tailored to your D7 module footprint. Before running anything, inspect what was created:

Image

Writing a Custom Content Type Migration

Auto-generated migrations handle standard field types well. Custom CCK fields, computed values, or non-standard formatters need explicit YAML definitions. Here's a realistic example - a D7 Event content type with a date range field:

Image

Image

---

Path 2: Classic Drupal 9/10/11 → Drupal CMS 2.x

This is the most common scenario at agencies right now: modern Drupal running well, but built before Recipes and Canvas existed. There is no data migration here - your content stays exactly where it is. What you're adopting is a new site-building layer.

Step 1: Inventory Your Current Setup

Image

Step 2: Add Drupal CMS Packages to Composer

Image

Step 3: Apply Recipes Selectively

Image

Because recipe config actions use createIfNotExists, this is safe on a live codebase - it will not overwrite your existing SEO or media configuration; it only fills in missing pieces.

Step 4: Making the Canvas Decision

This is where teams stall. If your current site uses Layout Builder or Paragraphs for page composition, official tooling to migrate into Drupal Canvas does not yet exist as of mid-2026. Your real options today:

• Option A - Hybrid adoption (most common): Keep existing Layout Builder/Paragraphs pages untouched. Use Canvas only for new pages, landing pages, and templates going forward.
• Option B - Manual high-value rebuild: Identify your top 10-20 highest-traffic pages. Rebuild those in Canvas using Mercury components. Leave the rest.

• Option C - Wait: If your site has thousands of Paragraphs-based pages, holding for official migration tooling may be the most pragmatic decision - a visible discussion at DrupalCon Rotterdam.

  ---

Path 3: WordPress / Other CMS → Drupal CMS 2.x

This is the highest-complexity path but increasingly common as organizations exit proprietary platforms for digital sovereignty and cost reasons.

The Contrib Stack

Image

A Real WordPress-to-Drupal Migration YAML

This example extracts WordPress posts from a side-by-side MySQL database and loads them into Drupal CMS article nodes:

Image

Image

Handling Media: The Hardest Part

Media is where CMS migrations to Drupal quietly break - broken image paths and dead embedded media are among the most common post-launch complaints.

The problem: body content migrated as raw HTML still contains <img src="/wp-content/uploads/..."> paths referencing the old platform. Two strategies fix this:

Strategy A - Migrate files first, rewrite src attributes after

Image

Strategy B - Use the file_import process plugin

Image

Always run a dedicated media migration pass before your content migration, so file entities exist before nodes try to reference them.

---

The Six Most Common Migration Pitfalls (and How to Fix Them)

⚠ Pitfall 1 Migration is busy with another operation: Importing

The most frequently encountered Migrate API error. It happens when a migration process is killed mid-run (Ctrl+C, server timeout, PHP fatal) and the status lock isn't cleared.

The fix:

Image

⚠ Pitfall 2 Skipping the Content Audit Phase

A reliable migration follows six stages: audit, content mapping, environment setup, content migration, media migration, and SEO preservation. Skipping a stage tends to resurface later as a launch-day fire drill.

A full pre-migration audit must cover:

• Total row counts per content type and per file type
• Fields with data in fewer than 5% of records (candidates for dropping)
• Taxonomy terms with zero content references (clean up before migrating)
• Broken internal links in body content (fix at source before migrating, not after)
• User accounts with no content (migrate only active users)

⚠ Pitfall 3 Not Planning for Delta Migrations

Initial migration runs are never the final run. Between your first migration pass and go-live, editors will keep publishing on the old platform. You need a delta migration strategy - re-running migrations to pick up records created or updated after the initial pass.

Image

⚠ Pitfall 4 Incorrect URL Alias Handling

After migration, old URLs may lead to 404 errors if not redirected correctly. Set up 301 redirects for old URLs to preserve SEO and user experience.

The pathauto module will regenerate URL aliases on save - which is exactly what you don't want post-migration if your old URLs had a different pattern. Disable Pathauto auto-generation on migrated content by setting path/pathauto to 0 in your migration YAML (as shown in the WordPress example above).

Image

⚠ Pitfall 5 Migrating Roles and Permissions Too Early

If you migrate users before your Drupal CMS roles and permissions are fully configured, user role assignments land in the system referencing role IDs that either don't exist or have different permission sets than intended.

The correct order:

1. Configure roles and permissions on the destination site first

2. Export config with drush cex

3. Then run upgrade_d7_user or equivalent user migration

4. Verify a sample of migrated users have the expected roles before migrating content

⚠ Pitfall 6 Not Rolling Back Cleanly Between Test Runs

During development and testing, you'll run migrations many times. Not rolling back cleanly between runs leads to duplicate content, inconsistent map tables, and cascading lookup failures.

Image

---

Migration Strategy: Choosing Your Cutover Approach

Beyond the technical tooling, the cutover strategy matters as much as the code. Three patterns dominate real-world projects:

Realistic timelines from field experience: small projects 6-12 weeks, medium-complexity 3-6 months, large enterprise migrations 6-12 months or more. These aren't conservative padding - they reflect what competent, well-resourced teams actually take when they don't skip the audit and planning phases.

---

After the Data Lands: Apply Recipes

This is the step migration guides most often omit. Migrate moves your content - it does not configure Drupal CMS's site-building layer. After your data migration validates cleanly, apply the relevant recipes:

Image

---

What to Watch at DrupalCon Rotterdam 2026

• Layout Builder & Paragraphs → Canvas migration tooling - the single most-requested missing piece; community proposals are expected in the Drupal CMS track
• The Migrate Drupal deprecation path - what officially replaces D6/D7 upgrade tooling in Drupal 12.x and beyond
• Delta migration patterns for headless and API-sourced content - increasingly relevant as organizations move off SaaS headless platforms

• Case studies from the Digital Sovereignty track - real migration stories from organizations exiting proprietary CMSs, with full technical detail

  ---

Summary

• Migration to Drupal CMS 2.x is three different problems depending on where you start:

• Drupal 7 sites use the core Migrate API + Migrate Drupal, with urgent deadline pressure and the 11.4+ deprecation on the horizon
• Classic Drupal 9/10/11 sites need no data migration - selective Recipe adoption and a deliberate Canvas strategy is the whole project
• Other CMS platforms need custom Migrate API source plugins, a full content audit, delta migration planning, and a clear cutover strategy

• In every case, the six pitfalls covered in this post - stuck migration locks, skipped audits, missing delta runs, broken URL aliases, wrong sequencing of users and roles, and unclean rollbacks - account for the majority of timeline blowouts. Most of them are avoidable with upfront discipline.

• ← Post #1: Getting Started with Drupal CMS 2.x: Site Building with Recipes

• → Post #3: AI-Powered Drupal: Integrating LLMs and Agentic Architecture

  ---

  References

• Migrate API Overview - drupal.org/docs/drupal-apis/migrate-api/migrate-api-overview
• Debugging Migrations - drupal.org/docs/drupal-apis/migrate-api/debugging-migrations
• Migrate Drupal Module (Deprecated 11.4) - drupal.org/docs/.../migrate-drupal-module
• Drupal Migration: Tools & Strategies 2026 - o8.agency
• Drupal Migration Guide for WordPress & Legacy CMS - innoraft.ai
• Migration to Drupal CMS: Complete Guide - sparkfabrik.com
• DrupalCon Rotterdam 2026 - events.drupal.org/rotterdam2026

---

🎟️ Join Us at DrupalCon Rotterdam 2026

Migration paths, Canvas tooling gaps, and the future of Migrate Drupal will all be live conversations in Rotterdam, 28 September - 1 October 2026.

👉 Register for DrupalCon Rotterdam 2026