Magento 2 Migration - The Ultimate Guide

The day has come.

Adobe (new owner of Magento) ended support for the 12-year-old Magento 1.x release line for both Magento Commerce and Magento Open Source on June 30, 2020.

What does this mean to a small business owner?

If you didn't migrate Magento 1 to 2, you’re on your own with anything your website may require.

Official support has ended, so don't expect any more official patches or security updates.

The time for Magento 2 migration has come.

I’m going to help you make the transition.

This guide will walk you through migrating a stock Magento 1 installation (with sample data) to a fully functional Magento 2 store.

I’ll outline possible issues that may arise during or after migration and suggest fixes.

How will this be helpful?

Except for highly customized shops, a typical Magento 1 store is not much different from a stock installation.

By following this tutorial, you’ll be able to migrate M1 to M2 yourself, saving your business thousands of dollars in developer fees.

However, if you would like an experienced developer to make sure your migration goes smoothly the first time, then you may find out more about our professional service here.

P.S.: Make sure to backup your database and files before you attempt to move to M2. There may be issues, and it is important to have a Plan B just in case.

Also, consider test-driving the migration process on a staging environment first. Make a copy of your website somewhere (on a different server preferably) and practice your update steps there.

Listen to three Magento gurus talking about M1 to M2 transition.

The 5-Step Magento 1 to Magento 2 Migration Process

1. Stock M2 installation

2. Data migration

3. Theme migration

4. Migrating extensions

5. Test, test, test

Step 0: Software and Hardware Requirements

Magento 2 will run poorly on outdated software, and it won’t work on PHP 5.

Your server should have the following programs installed:

• PHP: 7.0.13+ or 7.1.x

• MySQL: 5.6, 5.7 or MariaDB 10.0,10.1,10.2 or Percona 5.7

• The following PHP extensions: bc-math, ctype, curl, dom, gd, intl, mbstring, mcrypt, hash, openssl, PDO/MySQL, SimpleXML, soap, spl, libxml, xsl, zip, json, iconv

There are also certain hardware recommendations:

• At least 2G of RAM minimum

• 24GB+ SSD (Solid State Drive)

M2 won’t run well with less than 2G of RAM, and SSD technology will cause it to run much faster.

For more on the topic, read my previous post.

Step 1: Stock Magento 2 Installation

Transition to Magento 2 starts by installing a fresh copy of the latest Magento 2 software.

Let’s head over to the official website and grab the latest version of M2 Open Source.

As of time of this writing, that’s 2.3.0.

Download the latest Magento 2 software

Once downloaded, install it on a basic VPS (virtual private server) with 2G of RAM and 24G of SSD space.

I am using Nginx and PHP-FPM 7.1.

It’s easier than ever to pair Nginx with Magento 2 since the latter comes with a premade configuration file, nginx.conf.sample.

When everything is ready, let’s open up a browser and start the installation process.

Installing Magento 2: Step 1

The readiness check failed since I had quite a few PHP extensions missing.

Missing Extensions While Installing Magento 2

I went ahead and installed the missing software with the following command (I was using Debian 9):

Finally, step 6:

Installing Magento 2: Step6

Press the “Install Now” button to begin.

Install Log

Before long, the “Success” message will appear. For this example, it took me about half a minute.

Success!

Now that we have a fresh Magento 2 store, it’s time to migrate the data from the old M1 site.

In our case, the old Magento 1 site is not actually that old.

It’s just a fresh Magento 1.9.3.9 install loaded with sample data.

Magento 1 with Sample Data

You can download it from the official website.

Magento 2 Data Migration

The Magento team has simplified the Magento 2 migration process with an automatic Magento Migration Tool (MMT).

This program will transfer the data from your old M1 installation to the new M2 store.

Notice: You will need SSH (Secure Shell) access to perform a migration. Obtain it from your system administrator or your hosting support team.

Install the MMT from repo.magento.com using a PHP package manager software called composer.

If you haven’t installed composer, go ahead and do so now. Visit the Getting Started page on the official website for more information.

The Magento Migration Tool installation will place the files into a Magento 2 folder, which I’d setup in the previous step.

The following commands should do the trick, so run them inside the folder:

Take note of the 2.3.0 at the end of the second command. That is our M2 platform version.

If you’re migrating to a different version, change the command accordingly.

Upon running the composer require, the system will ask you for your authentication keys.

Get these by heading over to My Profile on Magento Marketplace website.

My Profile Magento Marketplace

Click on Access Keys under My Products menu.

Access Keys Magento Marketplace

Create a new Access key if necessary.

Then use the Public Key as a username and the Private Key as a password.

Once you enter that information, you should be able to install the data migration tool successfully.

Next, we’ll need to configure the tool.

Go to the Magento 2 root folder and find the following directory:

Copy config.xml.dist file to config.xml.

Substitute 1.9.3.9 with your site’s Magento 1 version and change opensource-to-opensource to opensource-to-commerce if you are migrating from the Community Edition to Enterprise (now known as Commerce).

Now open config.xml and find the code block below:

Then enter Magento 1 and Magento 2 database credentials.

Include password attribute like this:

Inside the <options> tag is another mandatory field to specify - <crypt_key>:

You can find your M1 crypt_key within the app/etc/local.xml file inside your old site’s root folder.

Settings Migration

Now, we start the actual data migration.

We first migrate settings, so head over to the M2 root folder and run:

Make sure to specify the correct path to your config.xml.

In our case, there were no errors, so the settings migration went fine:

Of course, this is a simple case and your store may be more complex than a stock installation.

If so, consider changing the following default setting in the XML configuration file:

vendor/magento/data-migration-tool/etc/opensource-to-opensource/1.9.3.9/config.xml:

Copy this to settings.xml before editing.

And don’t forget to set the right filename in config.xml!

Now open up settings.xml and study its contents, but it’s pretty self-explanatory.

If you need to ignore a setting, you do:

To rename:

You should be able to set up settings.xml any way you need.

Initial Data Migration

Now, we’re ready to transfer orders, customers and the actual store data. Do this by inputting the following command:

When I ran it, I got the “Integrity Check failed” message along with a bunch of errors:

Let’s fix them one by one.

The first error, “Foreign key constraint fails,” is actually a pretty simple issue:

We just have to delete any orphaned records from the specified tables:

The second error was “Field is not mapped”:

Here's the manual way to do this, but if you'd like to save some time, there's also an automated method (scroll down a bit).

1. Manual Way

To fix this one, just exclude the fields in question from the map-eav.xml file:

Since it’s under the EAV step, the correct file is map-eav.xml.dist.

You can choose to rename map-eav.xml.dist to map-eav.xml, or leave it as it is, but if you do rename it, don’t forget to change the config.xml file as well.

Let’s open up the map-eav XML file and add the following lines inside the <field_rules> </field_rules> tags:

These lines tell the migration tool to ignore the unmapped field.

After modifying any XML file, make sure to add an “-r” (reset) switch to the migrate:data command so the changes are picked up:

The next issue involves a message saying that the “Source documents are not mapped.”

You can take care of this issue manually, as I’ve done below, but there’s also an automated method that I’ll describe next.

By “documents” the tool means the DB tables.

We have to work with the XML map file since it falls under the Map step:

Place ignore statements in that file like so:

You get the idea; we’re just adding ignore statements to the XML map file.

If it’s a document, we ignore the corresponding table, and if it’s a field, we ignore a table field.

Since this will require a bit of copying and pasting, it may take some time to complete.

For me, it took around half an hour to finally pass the integrity check.

2. Automated Way

This magic option will save you tons of time.

[NOTICE]: You can use --auto or -a option to ignore not mapped differences between source and destination to continue migration

Finally, I was able to successfully migrate all the data:

Now, if we open the newly migrated Magento 2 site, we’ll see something like this:

Data After M1 to M2 Migration

Our Magento 1 categories and images are missing, so we’re not quite done yet.

Migration of Media Files

Expect to manually transfer a few aspects of your site, such as images.

Important: If you store your media in a database (as Magento 1 can do), it will automatically get transferred to M2.

Just Sync it before data migration:

• Magento 1 backend menu > System > Configuration > Advanced > System

• Click on a Synchronize button

Synchronize Media

In this example, I’ve stored the media in a file.

To copy the data over to Magento 2, we simply copy the M1:media folder over to M2:pub/media:

After that, we have to reindex the Magento 2 store with the following command:

Then recompile it:

Now, our website should have all our M1 products, along with their images:

Magento 2 With Migrated Products

M1 to M2 Migration: Theme

You’ll save a lot of time by going with a premade Magento 2 theme.

You can port your existing M1 theme, but if you do that, prepare to dive deep into M2 internals.

In most cases, you are better off hiring a skilled Magento 2 developer.

A few things to keep in mind:

• The XML structure of M2 is different than that of M1, so you cannot simply copy and paste the layout files.

• M2 replaces the prototype JS framework of M1 with jQuery.

• CMS syntax is similar, so you can make CMS pages work with a little effort.

• I recommend basing your newly created M2 theme off the default Luma theme. This will give you a strong framework to work with.

• M2 features three running modes: default, developer, production. Use developer mode to develop, and then production mode once the site goes live.

Magento 2 Extension Migration

M1 plugins won’t work with M2.

There is no reliable (at least to my knowledge) M1 to M2 migration coding tool that magically turns a M1 module into a M2-compatible extension.

You’ll have to do most of the work manually.

My advice would be to make a list of extensions you’d like to have on your new M2 site.

Then either hire a Magento 2 developer (one who offers Magento migration services) to refactor your extensions or find alternatives for them yourself.

When Things Go Wrong

The Magento 2 migration process isn’t always smooth, and many things may not go as planned.

Below, you’ll find some of the most common issues you might come across while moving to M2.

1. Empty Category / Landing Page

After migration, you may find that some pages look like this:

Empty Page After Magento 2 Migration

Typically, this happens due to incorrect CMS syntax.

For example, a page can load static blocks with the following code:

This works with Magento 1 but not Magento 2.

You will need to change type=”cms/block” to class=”MagentoCMSBlockBlock”:

Those of you who are familiar with a MySQL command line could just run:

This will update all static blocks.

2. Missing Catalog Images

This issue might be hard to spot.

If your newly migrated M2 store has broken product images on all category pages, or just a few of them, there’s an easy solution.

Just regenerate the image cache with this simple command:

This will resize the product images and put them in the correct cache folders.

The command may take some time to run, so be prepared to wait.

3. “No Such Entity” Error

This error message may appear in various places, including when you’re reindexing your store, performing backend activities, or on some of the frontend pages.

From my experience, this error is usually related to corrupted store tables: store, store_group or store_website.

Login to the MySQL command line tool (or use phpMyAdmin) and inspect those tables.

Do all group_ids found in the store also exist in store_group?

Is this true for the website_id field and store_website table?

Here are a few helpful SQL queries:

If any of the above queries return non-empty results, you have a corrupt table.

Dive deeper and delete hanging records.

4. Double .html.html in Product Urls

Some users report having .html.html in almost all product urls after they move to Magento 2.

That happens because they have .html suffix in either url_key or url_path product attributes.

Here is how to get rid of it.

Warning: Your wrong .html.html urls might have already been indexed by google. To avoid loosing any traffic make sure you put .html.html -> .html redirect in place after you apply my fix.

Login to DB and issue the following commands:

Then reindex the database:

And .html.html should now be replaced with a single .html.

Delta Magento 2 Migration

After the initial data migration, and theme, customizations and extensions migrations, you are ready to go live.

The final step is to transfer any new orders, customers (and sometimes products) created in your production Magento 1 store since you first migrated data to Magento 2.

Obviously, starting from scratch isn’t an option since you’d lose all of your customizations.

That’s when delta migration feature comes handy.

Data migration tool allows you to migrate only specific changes.

You can run these incremental updates as often as you want.

The command is simple:

In our sample 1.9.3.9 -> 2.3.0 case, that would be:

Things to keep in mind about delta migration

There are a few things to remember while loading incremental updates:

1. Delta configuration doesn’t track every change that the Magento 1 database might have.

2. After an initial migration, do not remove or add products, orders, customers from and to your new Magento 2 database. This may break the delta migration process.

3. Do not change inventory levels in either of the databases (M1 and M2), or it may not be picked up by the delta script.

Test, Test, Test

I can’t emphasize it enough - thoroughly test your newly created Magento 2 before going live!

Make a list of ALL the features of your current Magento 1 and check them one by one.

Make sure all the payment methods work and the money is captured.

Test any complex shipping setups to make sure they work like they’re supposed to.

This may seem like common sense, but you would be surprised at the amount of mistakes you’d spot through regular check-ups.

At the end of the day, you want your shop to be stable, user-friendly and profitable.

You can’t expect any profits from a website that barely works.

A Few Final Words

Magento 1 to Magento 2 migration is no easy task, but with enough planning and attention to detail, you can pull it off with little-to-no downtime.

One important piece of advice I’d like to share:

Test drive your migrated Magento 2 store.

Test every bit of it: checkout, customer registration, product management.

Let me say a few words about load testing. This is when you put your new website under a simulated amount of average traffic.

How many people visit your Magento 1.x store a minute?

10, 50, 100?

Go ahead and see what happens to your Magento 2 site when 100 visitors hit it.

Does it become unbearably slow?

Do all the functions still work?

Can you checkout?

You want to make sure the site works well under every day traffic.

Once you’ve made sure all of that is in order, the next thing would be to pull the plug, make a DNS switch, and see your M2 site go live.

Did you move to M2 on your own, or did you seek out professional services? As always, you are very welcome to share your experience in the comment section.

All the best!

If you find this post interesting do not hesitate to sign up for our newsletter and join the 1472 people who receive Magento news, tips and tricks regularly.

Thank You!