Technical Guide

Mastering the Magento Data Migration Tool

Moving from Magento 1 to Magento 2 is not just a simple platform upgrade; it's a re-platforming architecture shift. The Magento Data Migration Tool is Adobe's official command-line interface (CLI) tool designed to help developers transfer data from M1 to M2 efficiently. While the tool automates much of the heavy lifting, successful migration requires a deep understanding of its configuration, quirks, and potential pitfalls.

What Data Actually Gets Migrated?

The tool is designed to move your store's critical assets, but it doesn't move everything. Understanding the scope is the first step to planning your migration project.

  • Store Settings & Configuration: This includes your system configurations, shipping settings, payment method configurations, email templates, and tax rules. However, note that some 3rd party extension configurations may not carry over if the M2 extension uses a different structure.
  • Main Data Entities: The bulk of the migration. This covers Products (Simple, Configurable, Virtual, Downloadable, Bundles), Categories, Customers (including address books and passwords), Orders (History, Invoices, Shipments, Credit Memos), and Wishlists.
  • Delta Changes: Crucially, the tool allows for "Delta" migration. This means you can migrate your data, continue to run your M1 store, and then catch up on any new orders or customer registrations that happened while you were building the M2 site.

What is NOT Migrated?
Frontend themes, layout XML files, JavaScript customization, and code-level customizations are NOT migrated. You must rebuild your theme (e.g., using Hyvä or Luma) from scratch. Additionally, 3rd party extension data is only migrated if the vendor provides a mapping file.

Pro Tip: Clean Your Data First

One of the biggest mistakes shops make is migrating "garbage" data. Old quotes, abandoned carts from 2016, and massive log tables can slow down your migration by hours or even days. Run a cleanup script on your M1 database to truncate `log_url`, `log_visitor`, `report_event`, and ancient quote tables before you begin.

Prerequisites for Success

Before you even install the tool, ensure your environment is ready:

  • Network Access: Your M2 server must be able to connect to the M1 database. If they are on different servers, you will need to whitelist the M2 server's IP address in the M1 server's firewall (MySQL port 3306).
  • PHP Configuration: Migration is memory-intensive. Set `memory_limit` to at least 2G or -1 (unlimited) in your CLI php.ini. Also, ensure `max_execution_time` is strictly unlimited.
  • Module Versions: Ensure that the version of the Data Migration Tool matches your Magento 2 version EXACTLY. If you are on Magento 2.4.6, you must use the 2.4.6 version of the tool. Mismatches lead to cryptic XML errors.

Step-by-Step Migration Workflow

1. Installation

We recommend installing the tool via Composer. This ensures that dependencies are managed correctly. 

composer require magento/data-migration-tool:2.4.7

Replace `2.4.7` with your specific version.

2. Configuration (The Hard Part)

After installation, navigate to `vendor/magento/data-migration-tool/etc/opensource-to-opensource`. You will see folders for different M1 versions (e.g., `1.9.4.5`). Choose the one closest to your M1 version.

You need to copy `config.xml.dist` to `config.xml` and `map.xml.dist` to `map.xml`.

config.xml: This is where you define your database credentials. You will have a ` ` node (for M1) and a `` node (for M2). You also define your `crypt_key` here, which must match the encryption key from your M1 `local.xml` file. Without this, user passwords and payment tokens cannot be decrypted.

map.xml: This file tells the tool how to transform data. If you have custom fields in M1 that don't exist in M2, the tool will fail unless you either:
a) Ignore them (using `` tags)
b) Rename them (using `` tags)
c) Transform them (using Handler classes)

3. The Three Modes of Migration

Migration must be run in a specific order:

Mode A: Settings

bin/magento migrate:settings vendor/path/to/config.xml

This migrates system configuration and website structure. It is fast (usually seconds). Warning: This connects to your M2 database and typically clears existing store configuration.

Mode B: Data

bin/magento migrate:data vendor/path/to/config.xml

This is the big one. It moves products, customers, and historical orders. Depending on your catalog size, this can take from 10 minutes to 48 hours. The tool runs an "Integrity Check" first to verify that all fields map correctly. If this fails (and it usually does on the first try), you must edit your `map.xml` file to resolve the specific field errors shown in the console.

Mode C: Delta

bin/magento migrate:delta vendor/path/to/config.xml

Once the main data migration is done, you can go live with your M2 testing. But your M1 site is still taking orders! The Delta mode installs database triggers (triggers begin with `trg_`) on your M1 database. These triggers capture every insert/update/delete. You run the Delta command periodically (or continuously via a daemon) to fetch these changes. This allows you to keep M2 synchronized with M1 up until the very second you switch your DNS.

Troubleshooting Common Errors

Error: "Source documents are not mapped"

Cause: You have a custom table or column in M1 that M2 doesn't know about.

Fix: Open `map.xml`. Add a `` rule for the specific table or column if you don't need it in M2.

Error: "Foreign key constraint fails"

Cause: Your M1 database has orphaned records (e.g., an order item referring to a product ID that no longer exists).

Fix: Enable `` in `config.xml` or clean your M1 database manually to remove orphaned rows.

Error: "Class not found"

Cause: This usually happens during EAV attribute migration if a custom attribute uses a source model validation class that hasn't been ported to M2 code yet.

Fix: You must create a skeletal module in M2 that defines this class, or map the attribute to a standard M2 class in `eav-attribute-groups.xml.dist`.

Post-Migration Checklist

Seeing "Migration Completed" in green text is a great feeling, but you aren't done yet.

  1. Put M2 in Production Mode: Compile code and static content.
  2. Reindex All: The migration tool disables indexers. You must run `bin/magento indexer:reindex` immediately after migration.
  3. Resize Images: M2 uses different image resizing logic. Run `bin/magento catalog:images:resize`. This can take a very long time, so run it in a `screen` session.
  4. Change Customer Passwords?: No! If you migrated the `crypt_key` correctly, your customers can log in with their existing M1 passwords.
  5. Test Payment Gateways: Tokenized credit cards (Vault) often need special handling. verify that stored cards still work.

Need Expert Help?

While the Data Migration Tool is powerful, it requires significant CLI knowledge and database expertise. A failed migration can result in mixed-up orders, broken customer logins, or corrupt category trees. If you prefer to have a team of certified professionals handle your migration with a "Zero Data Loss" guarantee, contact us below.