How to Upgrade to Magento 2.3: Update & Error Fixes

- E-Commerce, Magento 2

Magento 2.3 Features

In the following article, we describe how to upgrade your e-commerce website to Magento 2.3 – the latest version of our favorite e-commerce platform. Besides, you will find solutions of the most common issues related to the process. If you want to get all the latest benefits Magento offers, change the version of your platform immediately. This guide will teach you how to achieve this goal.

'

Magento 2.3 System Requirements

The first thing we’d like to draw your attention to is the Magento 2.3 system requirements. You always need to pay attention to them before upgrading to the latest version since your current setup can be outdated for the upgrade causing multiple issues and breaking the entire online store. Of course, you don’t want to have all these troubles, so check the Magento 2.3.x technology stack requirements to eliminate possible future problems.

Operating Systems

The supported operating systems for Magento 2.3 are Linux x86-64 distributions, such as RHEL, CentOS, Debian, Ubuntu, etc. What operating system do you use? Is it supported?

Memory Requirement

How many gigabytes does your system have? The minimum amount of RAM required for the upgrade to Magento 2.3 is 2GB. If you have less – create a swap file to prevent the upgrade fail.

Composer Requirements

If you want to contribute to the Magento 2.3 codebase or develop Magento extensions for the latest platform version, you need the latest stable version of Composer to be installed.

Web Server Requirements

While upgrading to Magento 2.3, you can use several options. First of all, it is Apache 2.2 or 2.4. Note that you must enable the Apache mod_rewrite to enable the server to perform URL rewriting and mod_version to enable flexible version checking for different httpd versions.

Alternatively, it is possible to use nginx 1.x to update your Magento version to 2.3.

Database Requirements

As for the database suitable for Magento 2.3, it is MySQL 5.6 or 5.7. At the same time, you can use several alternative options since the latest platform version is compatible with MySQL NDB Cluster, MariaDB, Percona, as well as other binary-compatible MySQL technologies.

PHP Requirements

And there are a plethora of PHP requirements regarding the upgrade to Magento 2.3. The two supported versions are 7.1.3+ and 7.2.x. At the same time, you need to install multiple extensions. You can find them here: Required PHP Extensions.

And don’t forget to enable PHP OPcache for performance reasons. Chances are, you should install it separately, see the PHP OPcache documentation for further information.

Also, note that the official Magento documentation recommends particular PHP configuration settings, such as memory_limit, to avoid common problems when using Magento. You can find them here: Required PHP Settings.

SSL Requirements

To upgrade your e-commerce store to Magento 2.3, a valid HTTPS security certificate is required. Note that self-signed SSL certificates are not supported.

TLS Requirements

It is also necessary to mention that both PayPal and repo.magento.com require TLS 1.1 or later. For further information, follow these links: TLS requirement for repo.magento.com & TLS 1.2 requirement for PayPal.

Mail Server Requirements

To upgrade to Magento 2.3, you need Mail Transfer Agent (MTA) or an SMTP server.

Supported Technologies

  • Redis 3.2 can be used for page caching and session storage;
  • Varnish 4.x or 5.2 can be utilized as well;
  • Elasticsearch: 5.2.x and 2.x for Magento Commerce; Elasticsearch PHP client version 5.2;
  • RabbitMQ 3.7.x is another supported technology that offers a more efficient way of publishing messages to queue and defining the consumers that receive the messages asynchronously;
  • Three master databases can be used in Magento Commerce to provide scalability advantages for different functional areas.

Recommended Optional Requirements

  • php_xdebug 2.5.x+ for development environments;
  • Mcrypt – PHPUnit 6.2.0 as a command-line tool.

Supported Browsers

Magento 2.3 usually support one major version earlier than the latest released version when it comes to browsers for storefront and admin:

  • Internet Explorer 11 or later, Microsoft Edge;
  • Firefox;
  • Chrome;
  • Safari for Mac OS;
  • Safari Mobile for iPad 2, iPad Mini, iPad with Retina Display starting from iOS 7 for desktop storefront;
  • Safari Mobile for iPhone 4 or later for iOS 7+ for mobile storefront;
  • Chrome for mobile storefront.

For further information, follow this link: Magento 2.3 System Requirements.

Upgrading to Magento 2.3

To upgrade Magento to 2.3 from the command line, your software should be installed by downloading the metapackage with the help of composer create-project or installing the compressed archive. You can use either the command line or the script to run the update procedure.

Note that both options require utilizing Composer and a command line interface. However, the script allows automating several of the upgrade steps. And don’t forget about prerequisites (we describe them below).

And if you cloned the Magento 2 GitHub repository, go right here. This article describes how to upgrade to Magento 2.3 for your particular case.  

Prerequisites

To prepare your environment to the upgrade to Magento 2.3, complete the following prerequisites:

  • Complete the Update and upgrade checklist to avoid possible errors during the process;
  • Set the pub directory root: create a subdomain or docroot that uses the Magento installation directory as its root, and run the System Upgrade utility using that subdomain if you already set the Magento root directory to <your Magento install dir>/pub;
  • Check the compatibility: verify that all environment settings are compatible with the system requirements described above;
  • Switch to maintenance mode: this will prevent access to your store while it’s being upgraded. To do that, run the following command:

Upgrade to Magento 2.3 via Command Line

Below, we describe how to upgrade to Magento 2.3 using the command line interface with the highest control level over the process. The more manual process of upgrading requires more time but provides some additional flexibility. Upgrading using the script process is a bit easier and less intensive and we will also describe it further in this post.

Create Backup

The first step in your update to Magento 2.3 is the backup of the existing composer.json file in the Magento installation directory.

Manage Packages

To run the upgrade successfully, you need to specify all the needed packages and remove any unneeded ones before going any further.

In case you are upgrading from Magento Open Source to Commerce, don’t forget to deactivate the Magento Open Source update. Use the following command to do that:

Now, let’s see how to indicate the Magento packages and the version of your update. For Magento Open Source, use the following command:

If you want to upgrade to Magento 2.3 Commerce, run the following one:

To specify additional packages, use the following command:

You can also remove unused packages, with the help of this one:

Update Autoload

Now, you have to update autoload. Open the composer.json file and find the “autoload”: “psr-4” section. It should include “Zend\\Mvc\\Controller\\”: “setup/src/Zend/Mvc/Controller/” like in the following example:

Modify Magento Updater

Chances are, you have already installed the Magento updater. Now, you have to modify it.

Firstly, backup and remove the old updater from the <Magento install dir>/update directory.

Secondly, create a corresponding Composer project. For Magento Open Source version 2.3.0, use the following command:

As for Magento Commerce version 2.3.0, use this one:

To use a repository with non-public packages, change the URL in –repository accordingly.

Thirdly, you have to move your project to the <Magento install dir>/update directory. Utilize the following commands to achieve this goal:

Update Metadata

Now, it is necessary to edit metadata. You have to update the “name”, “version”, and “description” fields in the <Magento install dir>/composer.json file. Note that it is a superficial process – not functional.

Apply Updates

Finally, you can apply the updates. You might have already used the necessary command on previous upgrades:

Clean Magento Cache

Now, when the update is applied, you have to clean the cache. Use the command provided below:

You should also clear caches and generated content of the var and generated subdirectories manually:

If you use Redis, Memcached, or another cache storage, clear the cache there too.

Update Database Schema

Now, the upgrade to Magento 2.3 requires to update the database schema and data. Use the following command:

Disable Maintenance Mode

If everything is ok and no errors occurred, you can disable the maintenance mode. Use this command:

Restart Varnish

Don’t forget to restart Varnish if you use it. Use this command:

Check Update

How to check whether the update to Magento 2.3 is successful? Open your storefront in a browser. If it doesn’t load correctly, the upgrade failed. We provide multiple issues and their resolutions below.
If the application prompts the following error – We’re sorry, an error has occurred while generating this email – you have to:

  • Reset the filesystem ownership and permissions as a root user.
  • Clear the following directories: <your Magento install dir>/var/cache, /var/page_cache, and /generated/code.

Now, check your storefront in your web browser again. If your store still loads incorrectly, try to find the reason in the corresponding section of this article.

Upgrade to Magento 2.3 via Script

Now, we’d like to draw your attention to another approach to the Magento 2.3 upgrade. You can use a script to simplify the procedure described above make it semi-automated.

Note that to upgrade to Magento 2.3 via script, you have to update to PHP 7.1 or 7.2.

Also, don’t forget that you should use the manual process if you don’t want to override previously made updates to the values the upgrade script affects. If it is not a problem, then the script will:

  • Update Magento with the 2.3 requirements;
  • Create a backup of the composer.json file;
  • Specify the new Magento metapackage version;
  • Update the “require-dev” and “autoload”: “psr-4” sections;
  • Back up and update the magento/updater, if it is installed;
  • Update the “name”, “version”, and “description” fields.

As you can see, the script dramatically improves the standard upgrade to Magento 2.3 automating multiple processes. Let’s see how to use it.

Download Script

Download or copy the script file here: Magento 2.3 Update Script.

Script Options

To show script options, use the following command:

Run Script

You can run the script via the command below:

Apply Updates

Now, you can apply the updates. Use the command mentioned above:

Clean Magento Cache

Now, when the update is applied, you have to clean the cache. Use the following command:

Clear caches of the var and generated subdirectories manually:

If you use Redis, Memcached, or another cache storage, clear the cache there too.

Update Database Schema

Now, the upgrade to Magento 2.3 requires to update the database schema and data. Use the following command:

Disable Maintenance Mode

If everything is ok and no errors occurred, you can disable the maintenance mode. Use this command:

Restart Varnish

Don’t forget to restart Varnish if you use it via the following command:

Check Update

Use the same approach to check whether the Magento 2.3 update was applied successfully: Open your storefront in a browser.

If the application prompts the following error – We’re sorry, an error has occurred while generating this email – you have to:

  • Reset the filesystem ownership and permissions as a root user.
  • Clear the following directories: <your Magento install dir>/var/cache, /var/page_cache, and /generated/code.

Now, check your storefront in your web browser once again. If your store doesn’t load correctly, try to find the reason in the corresponding section of this article.

For further information about the upgrade procedure, follow this link: Magento 2.3 Command-Line Upgrade.

What if Things Go Wrong?

As promised above, we provide several common issues that occur during the upgrade as well as explain how to fix them. Let’s see what disturbs Magento users when they want to get a new platform’s version.

Component Dependency Issue

This problem may occur when you upgrade Magento via Setup Wizard at the Readiness Check step. Dependency conflicts are usually caused by third-party extensions depending on some old Magento 2 components. To resolve the issue, you have to uninstall all custom extensions. Don’t worry: you will reinstall them after the system is updated.  

Another reason for this issue is a changed composer.json file. Restoring composer.json to the original version usually helps. After doing that, run Setup Wizard one more time.

Directory Issue

To prevent this error, don’t run php bin/magento setup:upgrade right after the upgrade. If it occurs, you have to delete the var/di folder. Next, change permissions of var and pub folder to 777:

Run the following two commands:

&

It should solve the problem.

Memory Issue

At the beginning of this post, we mentioned that the minimum amount of RAM necessary for upgrading to Magento 2.3 is 2GB. If you have less, you will encounter the ‘Cannot allocate memory’ error during the upgrade. It means that not enough RAM is allocated to PHP processes.

Setup Namespace Issue

While upgrading to Magento 2.3, you may also face the “There are no commands defined in the “setup” namespace” message. The corresponding error is fixed as follows:

You have to give full permission to var and pub folders. Use the following command:

Next, you have to inspect your third-party extensions. Every extension’s module.xml should have setup_version in it:

You may also inspect your composer.json file. Sometimes its errors might be a reason for this issue.

Upgrade Command Issue

If php bin/magento setup:upgrade isn’t working, you have to inspect all custom modules. Usually, their internal problems cause the issue. As we’ve already mentioned, you can delete them, upgrade to Magento 2.3, and then reinstall the extensions.

Also, note that you may also try to clean generated or var/di, var/generation folders. This procedure helps sometimes.

For further information, follow this link: Magento 2 Upgrade in 3 Easy Steps.

Upgrading from Magento 2.2.X to 2.3.0

Navin Bhudiya asks on StackExchange how to upgrade from Magento 2.2.X to 2.3.0. He uses the following two commands:

&

We’ve mentioned them above in our guide, but Navin gets the following result:

As you might have already guessed, some steps are missed. So, follow the guide above carefully to avoid the problem. According to Daniel, the error is caused by fabpot/php-cs-fixer, so he recommends to remove unused packages with the help of the following command:

And make sure you are specifying all the required packages:

Follow the guide above, and you won’t get into this trouble!

Magento 2.3 Composer Update

JG Cabanas tried to upgrade his 2.2.6 Magento install using Composer. Instead of Magento 2.3, he faced the following issues:

As we’ve mentioned above, it is necessary to edit the composer.json file, since Magento 2.3 has new dependency versions. Only then, you can run the composer update command. Peter Dohogne recommends running the script update. Besides, he proposes to check whether your Composer version is compatible.

Your executable version of Composer should be

Installed composer/composer package version for Magento 2.2.6:

Dependencies with composer/composer requirements and constraints:

The installed composer/composer package version after the Magento 2.3.0 upgrade:

Dependencies with composer/composer requirements and constraints:

We recommend you to follow the guide below to avoid this problem. Carefully check every step and make sure that you do everything as it is described in the article or official documentation.

Third-Party Extensions Issue

Ashish Viradiya complains that while upgrading from Magento 2.2.5 to Magento 2.3.0, some third-party modules cause an error when he applies the composer update command.

He also tried to use the composer require [ModuleName] 2.3.0 –no-update command, but it caused the following error:

It seems that the problem can be solved by removing all the third-party extensions and reinstalling them after the Magento 2.3 upgrade.

At the same time, Aasim Goriya recommends checking the extension’s composer.json file and adding the latest PHP and framework version:

Next, it is necessary to find your third-party extension name in the /vendor/composer/installed.json file and add the latest PHP and framework version there. To apply the changes and the update, run the composer update command.

Magento 2.3 Installation Parse Error

Pradeep Sanku is trying to install Magento 2.3.0 on localhost. He gets the following issue:

in /var/www/html/m230/vendor/magento/framework/Filesystem/Directory/Write.php on line 35.

Mukesh Prajapati points to the fact that Magento 2.3 doesn’t support PHP 7.0 and works with 7.1 or 7.2. He recommends upgrading to the latest one to solve the problem.

But it is easy to avoid such problems, you only have to read prerequisites carefully and then follow all the steps of the upgrade guide.

Sample Data Issue

Haim had a clean Magento 2.2.6 installation with sample data installed via composer. All attempts to upgrade to Magento 2.3 caused the following error:

The issue was caused by the sample data. You have to remove it before the upgrade to Magento 2.3 via the following command:

Invalid Template File

Sanjay Jethva tries to upgrade from Magento 2.2.6 to 2.3.0 but gets the following error:

Tho assumes that it is a problem of the local installation caused by the fact the Magento instance is running on Windows. The user recommends fixing the vendor\magento\framework\View\Element\Template\File\Validator.php file. To solve the problem, go to line 114 and change the line number and replace the following snippet

With

According to Sanjay, it fixes the problem only partially: the website is loading but the home page and admin login show a blank page. Go to StackExchange and help him if you know the correct resolution!

Command “Update” Failed

Borde91 describes another problem that occurs while upgrading to Magento 2.3:

And the user immediately provides the resolution. According to Border91, you have to run the following commands:

Setup-Upgrade Issue

If after the Magento 2.3.0 upgrade, the system informs you that ‘Zend\Mvc\Controller\LazyControllerAbstractFactory’ is not found, you have to edit the composer.json autoload section as follows:

Next, run the command below:

Universal Resolution

And don’t forget about the universal resolution of all issues related to the Magento 2.3 upgrade – you can downgrade to the previous version! Use the CLI algorithm described in this article but put an older version number instead of 2.3.

Final Words

Although the Magento 2.3 upgrade seems to be a little bit complicated, especially due to the high amount of reported problems, it is still not rocket science, so you can manage everything. Choose the script installation if the CLI one seems to be too difficult. If any problems occur, always go to StackExchange for help!

'