How to fix errors while upgrading to Magento 2

You are currently viewing How to fix errors while upgrading to Magento 2

7 errors encountered while migrating, and how to fix them!

As newer versions of Magento are released from time to time, merchants seek out a smooth upgradation process.

Magento 2 was released in 2015 with revamped architecture and exciting new features. Magento 2 is now considered the top choice of eCommerce business owners. As Magento 1’s popularity diminishes and Magento 2 takes its place instead, businesses enlist migration services. The process of migration is not always smooth and can prove to be a challenge for some businesses.

The Data Migration Tool (DMT) is a command-line interface used for migrating data from one Magento version to another. This tool verifies consistency between database structures, tracks the transfer progress, verifies tests and creates logs.

The tool operates in 3 modes which are shown in Figure 1.

  1. Settings Mode  

Manages and migrates configuration settings 

  1. Data Mode  

Migrates data in bulk to the destination database  

  1. Delta Mode  

Transfers incremental data updates to Magento storefront and admin panel while running previous migration modes  

Figure 1: DMT modes 

Before we discuss the issues faced while migrating, let’s briefly talk about the process of migration itself.  

You can make a backup of your data with the following command: 

mysqldump -uadmin  -p databasename target> databasename target.sql

In order to initiate the migration, you will use the following command:  

bin/magento migrate:data [-r|--reset] [-a|--auto] {<path to config.xml>}

Now that we have covered the basics of getting started with migration, let’s move on to explore some of the most frequent issues faced when using DMT, and how you can solve them!  

1. Mapping Issue with Fields and Source Documents  

Have you ever seen the following error show up on your screen while migrating?  

  • bash Source documents are not mapped: <EXTENSION_TABLE> 
  • bash Source fields are not mapped. Document: <EXTENSION_TABLE>. Fields: <EXTENSION_FIELD> 

An error like this appears when the Data Migration Tool is trying to check for consistency between the source and destination databases. Internal tests are run to check for data consistency between tables and fields. Instead of the word ‘Source’ in the error message, you may also see the word ‘Destination’ which implies the same problem.  


To resolve this error, here are some practical solutions you can adopt:  

  1. Configure the Data Migration Tool  
    Executing the –a argument will help auto-resolve errors and will ensure that the migration does not stop  
  1. You may also choose to ignore database entities that are not needed by adding <ignore> tag to the entity in the map.xml file  

Here is how you can insert the <ignore> tag:  





            <!-- Ignore `sales_flat_invoice_grid` table --> 




            <!-- Ignore `address_id` field of `sales_flat_order_address` table --> 








2. Classes not mapped in records

While migrating an error like this may also appear: 

Class <extension/class_name> is not mapped in record <attribute_id=196>

This error occurs at the Entity Attribute Value migration step. Usually, it is due to the missing class of an extension.  


You resolve this error, you can:  

  1. Reinstall the existing extension 
  1. In the eav-attribute-groups.xml.dist, add the attribute that causes this error to <ignore> 
  1. Add class mapping using class-map.xml.dist file  

3. Foreign Key Constraint Failure  

You may also encounter an error like this:  

Foreign key <KEY_NAME> constraint fails on source database. Orphan records id: <id_1>, <id_2> from <child_table>.<field_id> has no referenced records in <parent_table> 

This occurs when there are missing database records in the parent_table, to which the field_id of the child_table is pointing to 


Some viable solutions for this can be:  

  1. Delete the records from the child_table if not needed. 
  1. Disable the Data Integrity step by modifying the DMT’s config.xml.

4. URL Rewrite Duplication  

There are duplicates in URL rewrites: 

Request path: towel.html Store ID: 2 Target path: catalog/product/view/id/10 

Request path: towel.html Store ID: 2 Target path: catalog/product/view/id/12 

The above error occurs when two entries use the same request path and store ID pair but with two different target path values. The target path in a URL must be specified by a unique pair of request path + store ID.  


Resolution to this can be to enable the auto_resolve_url_rewrite_duplicates in the config.xml file. This configuration adds a hash-string to the conflicting records of URL rewrite and shows the resolution result in the command line interface.  

5. Entity Mismatch  

Mismatch of entities in the document: <DOCUMENT> Source:



This error usually shows up when a customer places an order while the store is under active migration. To be precise, this occurs during the volume check setup (the stages are shown in Figure 2 below). This is when the Adobe Commerce database record encounters a mismatch between the original destination, and the final destination. It is common when a store is under migration for the website to say so and not take any orders. But some stores do allow orders to be compiled, and as soon as migration is done, those orders are automatically given the status of placed orders.   


A possible solution to resolve this error would be to run the Data Migration Tool in delta mode to transfer incremental changes. 

Figure 2: Check-stages for migration 

6. Deltalog not installed  

You may encounter this error as well:  

Deltalog for <TABLE_NAME> is not installed 

This means that deltalog tables (with prefix m2_c1_*) were not found. Data Migration Tool (DMT) installs these tables during data migration as well as database triggers which track changes and fill deltalog tables.  

Encountering this error means that you are trying to migrate from a copy of the store and not the live store itself. Copy does not contain triggers and deltalogs needed to complete delta migration therefore resulting in a failure. 


To troubleshoot this, testing of the migration process needs to be done. A specialized team is responsible for carrying out testing and the process usually entails scoping, dependencies/interactions, test cases, non-functional testing, and functional application tests.  

Here are some important arguments for migration configuration:  

bin/magento migrate:settings [-r|--reset] {<path to config.xml>} 

[-r|–reset] stands for an optional argument that starts the migration from the beginning, which can be used for testing migration. 

[-a|–auto] is also an options argument that prevents the migration from stopping if it encounters integrity check errors. 

{<path to config.xml>} is the absolute file system path to the migration tool’s config.xml file: this argument is required. 

7. MySQL Packets 

MySQLError1153 – got a packet bigger than ‘max_allowed_packet’ bytes 

This error occurs when MySQL is running in default settings.  


To solve this error, use the following steps.  

  1. For the client, specify the following command: 
mysql --max_allowed_packet=100M -u root -p database < dump.sql 
  1. Change the my.cnf or my.ini file (usually found in /etc/mysql/) under the mysqld section and set:  

You can also use the MySQL console to log these commands:  

set global net_buffer_length=1000000;  

set global max_allowed_packet=1000000000; 

We have discussed 7 common errors that one can encounter while upgrading Magento versions and migrating data. If you are considering migrating your own e-store to Magento or if you are considering upgrading your Magento version, it’s better to discuss with experts who have hands-on experience.  

At Integriti, we have a capable team of web developers who can make your migration process smoother! Explore our Magento development services here.