Run the tool

Edit on GitHub
Log an Issue

Magento Commerce only

The content on this page is for Magento Commerce only. Learn more
The Upgrade Compatibility Tool is an ALPHA version with limited scope, available for all Magento Commerce merchants, and only validating PHP Magento APIs and GraphQL schema. If you are a Magento Commerce user you can download it at the Magento repo.

The Upgrade Compatibility Tool ALPHA is a command line tool that checks a Magento instance against a specific version by analyzing all the non-Magento modules installed on it.

The Upgrade Compatibility Tool identifies potential problems that must be fixed in your custom code before attempting to upgrade to a newer version of Magento.

The tool returns a list of errors and warnings that you must address before upgrading to a new version of Magento.

Use the Upgrade Compatibility Tool

Execute the tool by running the following command:

1

bin/uct upgrade:check INSTALLATION_DIR

The INSTALLATION_DIR value is the directory where your Magento instance is located.

We recommend running the following command to avoid memory limitations:

1

php -d memory_limit=-1 /bin/uct

We also recommend using the -m command to run the tool against a specific module.

To see Upgrade Compatibility Tool command options and help:

1

bin/uct --help

GraphQL schema compatibility verification

The Upgrade Compatibility Tool also provides the option to introspect two GraphQL endpoints and compare their schemas looking for breaking and dangerous changes between them:

1

bin/uct graphql:compare https://domain1.com/graphql https://domain2.com/graphql

You must have running instance before and instance after the upgrade.

Arguments and options

Version

You can compare your current Magento installation with Magento versions >=2.3.

You must provide the version as a parameter when running the command:

1

bin/uct upgrade:check INSTALLATION_DIR -c 2.4.1

There are some limitations when running the previous command:

  • This parameter refers to any tag that identifies a specific version of Magento.
  • It is a requirement to provide this one explicitly; providing only the value of it will not work.
  • Provide the tag version without any quotation marks (neither single nor double): ‘2.4.1-develop’.
  • You should NOT provide older versions than the one you have currently installed, nor older than 2.3, which is the oldest one supported at the moment.

Full report

You can also get a full report containing both PHP-related errors and GraphQL. In this case, you must provide at least the following options:

  • --schema1=SCHEMA1
  • --schema2=SCHEMA2
  • INSTALLATION_DIR

Example of a bin/uct command

1

bin/uct upgrade:check --schema1=https://domain1.com/graphql --schema2=https://domain2.com/graphql -c 2.4.1 INSTALLATION_DIR

Output

The Upgrade Compatibility Tool provides a report identifying the affected non-Magento modules and the severity and description of the problem for every issue encountered:

Example with a list of errors/warnings

1
2
3
4
5

File: /app/code/Custom/CatalogExtension/Controller/Index/Index.php
------------------------------------------------------------------

 *   [ERROR] Line 84: Used nonexistent or non Magento API interface 'Magento\Catalog\Model\ProductRepositoryInterface'
 *   [WARNING] Line 6: Importing Magento @deprecated class 'Magento\Catalog\Model\ProductRepository'

The report also includes a detailed summary:

  • Installed Version: the version currently installed
  • Magento Version: the version you want to upgrade to
  • Running time: amount of time the analysis took to build the report (mm:ss)
  • Checked modules: amount of modules installed in the current magento version examined during the analysis
  • PHP errors found: amount of PHP errors
  • PHP warnings found: amount of PHP warnings
  • GraphQL errors found: amount of GraphQL errors
  • GraphQL warnings found: amount of GraphQL warnings
  • Total errors found: total amount of errors found
  • Total warnings found: total amount of warnings found
  • Complexity score: a figure that indicates how difficult is to upgrade from the current version to the new one

The lower this number is, the easier is to perform the upgrade.

Example of a summary report

1
2
3
4
5
6
7
8
9
10
11
12
13

 ------------------------ --------
  Installed version        2.3.5
  Magento version          2.4.1
  Running time             0m:48s
  Checked modules          60
  PHP errors found         162
  PHP warnings found       120
  GraphQL errors found     19
  GraphQL warnings found   0
  Total errors found       181
  Total warnings found     120
  Complexity score         482
 ------------------------ --------

Regarding the GraphQL schema compatibility comparison, the output would be very similar:

Example with a list of errors/warnings for GraphQL

1
2

 *   [ERROR] FIELD_CHANGED_KIND: ConfigurableProduct.gender changed type from Int to String.
 *   [WARNING] OPTIONAL_INPUT_FIELD_ADDED: An optional field sku on input type ProductAttributeSortInput was added.

See Developer information for more information.

Troubleshooting

Empty output

The M2_VERSION is the target Magento 2 version you want to compare to your Magento instance.

If after running this command:

1

bin/uct upgrade:check INSTALLATION_DIR -c M2_VERSION

the only output is Upgrade compatibility tool:

1
2

bin/uct upgrade:check /var/www/project/magento/ -c 2.4.1
Upgrade compatibility tool

the likely cause is a PHP memory limitation. Override the memory limitation by setting memory_limit to -1:

1

php -d memory_limit=-1 /bin/uct upgrade:check INSTALLATION_DIR -c M2_VERSION
© 2021 Magento. All rights reserved.