Magento 2 Data Migration Tool Guideline and Recommendations

magento 2 data migration

In this blog post, we’re going to give you a step-by-step guide to Magento 2 Data Migration. As you might know, transferring data is one of the essential phases in the Magento migration process. A small mistake can lead to serious consequences such as data loss.

This post will show you how to migrate data from Magento 1 to Magento 2 by using Magento Data Migration Tool.

What Is Magento Data Migration Tool?

The Magento Data Migration allows us to migrate multiple types of data from Magento 1 to Magento 2.

Thanks to this command-line interface, we can verify the consistency between DB structures of the two Magento versions, follow the transfer progress, create Magento logs, and make some verification tests.

Moreover, there are three different modes of Magento Data Migration Tool as the followings:

  • Settings mode: This helps to migrate important system configuration settings (e.g., shipping, payment, tax…) from Magento 1 to Magento 2.
  • Data mode: This helps to migrate main DB assets in your database in bulk.
  • Delta mode: This helps to migrate incremental changes after implementing the two previous modes (e.g., data added via storefront, order operations in Magento 1 admin panel…)

More specifically, the Magento 2 data migration tool allows us to migrate the following components:

  • Products (core attributes and content) and categories
  • Product ratings and reviews
  • Catalog URL rewrites
  • Customers
  • Orders (related invoices, shipments, and credit memos)
  • Attributes and attribute sets
  • Taxes and currencies
  • Catalog and shopping cart price rules
  • User accounts and assigned roles
  • All websites, stores, and store views

It’s worth noting that the Magento 2 data migration process doesn’t include:

  • Migration of media files (e.g., products and categories images, WYSIWYG editor,…)
  • Migration of theme (e.g., Javascript and XML layouts, style sheets,…)
  • Migration of Web services API credentials (e.g., REST, SOAP, XML-RPC).

Pros and Cons of Magento 2 Data Migration Tool

The Magento 2 Data Migration Tool is a valuable tool for transferring data from Magento 1 to Magento 2. However, like any tool, it has its own set of pros and cons. Let’s explore it in this section. 


  1. No Installation Charges: The Magento 2 Data Migration Tool can be installed without incurring any fees. Users can freely install the tool regardless of the data volume they need to migrate.
  2. Proper Documentation: Magento provides detailed documentation and instructions for using the Data Migration Tool. This documentation serves as a comprehensive guide, helping users navigate the migration process effectively.
  3. Flexibility in Data Transfer: The Data Migration Tool offers three migration modes: settings mode, data mode, and delta mode. Users can choose the mode that best suits their requirements, ensuring secure and efficient data transfer.
  4. Delta Migration: The Data Migration Tool enables users to migrate newly added information from the source cart to the target cart after the initial migration. However, it’s important to note that this feature only transfers data generated by Magento’s own extensions and does not cover third-party code or modules.


  1. Downtime on Source Store: After completing the data migration, users need to place their Magento 1 system in maintenance mode to switch to the new website. This process results in temporary downtime, which means the store is inaccessible to customers. Proper planning and communication are necessary to minimize the impact of this downtime on the business.
  2. No Official Support: Magento does not provide official support personnel for the Data Migration Tool, aside from the documentation. Users are solely responsible for the outcome of their migrations. While users can seek help from the Magento community, the assistance they receive is unofficial and may vary in quality and accuracy.
  3. Technical Expertise Required: The migration process using the Data Migration Tool is complex and requires a solid understanding of Magento’s architecture and data structures. Users need to possess advanced technical skills to navigate potential errors and challenges that may arise during the migration or hiring 3rd-party developers. Insufficient knowledge can result in errors or missing data.

Preparation For Magento 2 Data Migration

A Magento migration checklist is really important for a successful Magento migration. Before we start the migration process, make sure that you have checked the following issues:

  • The Magento Data Migration tool only supports Magento and over. Hence, if your store is running on the older Magento 1.x version, it’s a must to upgrade it to the latest versions of Magento 1 before carrying out the data migration process.
  • The Magento 2 data migration process will be easier if your Magento 1 and Magento 2 websites are on the same MySQL server.
  • You should make a backup of your Magento 1 database to handle possible risks of data loss or damage.
  • You must make sure that your network connection is strong and stable during the database transfer process.
  • You must cease all Magento 1 site’s activities on the backend (except order management) as well as disable all the cron jobs.

Magento 2 Data Migration Essential Steps

Step 1: Install the Magento Data Migration Tool on your Magento 2 website

Remember that your Magento 2 and the Data Migration Tool must be the same version. For instance, if your Magento version is 2.4.2, you must download the Data Migration Tool version 2.4.2.

Now, check your Magento 2 current version and then download the corresponding Data Migration Tool here.

Next, to install the data migration tool that has been downloaded, you must navigate to your Magento 2 root directory and run the following command:

composer config git
composer require magento/data-migration-tool:<version>

Note: <version> is your Magento 2 codebase version (e.g.: 2.2.5).

After tool installation, all of the mapping and configuration files will be contained in the following directories:

  • For Magento Open Source:

<your Magento 2 install dir>/vendor/magento/data-migration-tool/etc/ce-to-ce

  • For Magento Commerce:

<your Magento 2 install dir>/vendor/magento/data-migration-tool/etc/ce-to-ee


<your Magento 2 install dir>/vendor/magento/data-migration-tool/etc/ee-to-ee

Step 2: Configure Magento 1 and Magento 2 database

  • Firstly, let’s navigate to the path vendor/magento/data-migration-tool/etc/ce-to-ce/<magento1_version>
  • Secondly, you must change the name of config.xml.dist file to config.xml
  • Thirdly, you must enter the <crypt_key> and other details to access the source and destination database:
    <database host="db" name="magento1" user="root" password="root"/>
    <database host="db" name="magento2" user="root" password="root"/>

The crypt key is found at: <magento1_root_directory>/app/etc/local.xml

The <source> is the Magento 1 database and the <destination> is the Magento 2 database.

Step 3: Migrate the settings – Configure the “settings.xml” file

  • Firstly, let’s navigate to the path vendor/magento/data-migration-tool/etc/ce-to-ce/
  • Secondly, you must alter the settings.xml.dist file name to settings.xml
  • Thirdly, you must copy the settings.xml file into the path vendor/magento/data-migration-tool/etc/ce-to-ce/<magento1_version>
  • Fourthly, let’s modify the <settings_map_file> key tag to the path of settings.xml in the config.xml file & the settings.xml file
  • Fifthly, now you can launch the migration setting tool from the Magento 2 root directory by running the following command:
php bin/magento migrate:settings "vendor\magento\data-migration-tool\etc\ce-to-ce\<magento1_version>\config.xml" --reset
magento composer

Step 4: Migrate the data – Configure the “configure.xml” file 

  • Firstly, let’s navigate to the path vendor/magento/data-migration-tool/etc/ce-to-ce/<magento1_version>
  • Secondly, you must rename the map.xml.dist file to map.xml
  • Thirdly, you must update the <map_file> tag key to the full path of map.xml in the config.xml file
  • Fourthly, you can launch the migration data tool from the Magento 2 root directory by running the following command:
php bin/magento migrate:data "vendor\magento\data-migration-tool\etc\ce-to-ce\<magento1_version>\config.xml" --reset
repo magento
how to migrate data

Notes: It’s optional to use -r or –reset.

You can do the same for other data migration steps such as map, EAV, customer attributes, log, URL rewrites, etc.

Your Magento 2 data migration process was completed once you completed all of the above steps without any problems.

Next, it’s recommended to flush caches and reindex all indexers in Magento 2 store.

Step 5: Migrate incremental changes (optional)

As we have mentioned, the Delta mode is utilized for incremental updates migration since the last time you migrated data. To do that, you have to run the following command:

php bin/magento migrate:delta vendor/magento/data-migration-tool/etc/ce-to-ce/<magento1_version>/config.xml

How To Deal With Magento 2 Data Migration Errors?

Here are some common errors when migrating data and solutions.

Error 1: Source documents aren’t mapped: tigren_restorecancelled_order

  • What happens: Some documents (e.g., the tables) can’t be transferred because they don’t belong to Magento’s core tables and need to be ignored in the map.xml. 
  • Solution: You need to add the following code snippet to the source <document_rules> tag in the map.xml file:

Error 2: Source fields aren’t mapped. Document: sales_flat_quote_item. Fields: orderspro_is_temporary?

  • What happens: This is quite similar to the first error. Here, some fields (e.g., columns) can’t be transferred as they don’t belong to Magento’s core tables and need to be ignored in the map.xml. 
  • Solution: You need to add the following code snippet inside the source’s <field_rules> tag in the map.xml file:

Magento 1 to Magento 2 Migration Wrap Up

As you can see, Magento 1 to Magento 2 migrating is a relatively complicated process, which requires a lot of attention and effort.

If you don’t have enough knowledge and experience in Magento migration and Magento data migration, in particular, let Tigren help you! Contact us now to get a free quotation and consultation for your project – or find out more about our Magento migration service here!

With more than 10 years of experience in Magento development, we can guarantee your migration success.

Leave a Reply

Your email address will not be published. Required fields are marked *