Run the tool | Adobe Commerce Developer Guide

The Upgrade Compatibility Tool is a command-line tool that checks an Adobe Commerce customized instance against a specific version by analyzing all modules installed in it. It returns a list of critical issues, errors, and warnings that must be addressed before upgrading to the latest version of Adobe Commerce.

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

Use the `upgrade:check` command

The upgrade:check command is the main command to execute the tool:

bin/uct upgrade:check <dir>

The <dir> value is the directory where your Adobe Commerce instance is located.

The upgrade:check command runs the Upgrade Compatibility Tool and checks an Adobe Commerce customized instance against a specific version by analyzing all modules installed in it. It returns a list of critical issues, errors, and warnings that must be addressed before upgrading to the latest version of your Adobe Commerce.

Execute only when the project root (or main) directory is provided.

This command checks for core code changes for that specific Adobe Commerce instance, as well as all custom code changes installed in it.

However, you can run the core:code:changes command to analyze only core code changes for that specific Adobe Commerce instance. See Core code changes section for more information.

While you can use the graphql:compare command to compare two GraphQL schemas to check for any changes between them. See GraphQL schema compatibility verification section for more information.

Recommendations to use the `upgrade:check` command

The Upgrade Compatibility Tool requires at least 2GB RAM to run. This setting is recommended to avoid issues due to a low memory limitation. The Upgrade Compatibility Tool displays a question if you run the upgrade:check command with a low memory_limit setting.

Specify the -m option to run the tool against a specific module:

bin/uct upgrade:check <dir> -m[=MODULE-PATH]

Where arguments are as follows:

<dir>: Adobe Commerce installation directory.
[=MODULE-PATH]: Specific module path directory.

Use the `--help` option

To see the Upgrade Compatibility Tool command general options and help, run:

bin/uct --help

However, it is possible to run --help as an option when running a specific command, like bin/uct upgrade:check. This will return specific --help options for that command:

bin/uct upgrade:check --help

Available --help options for the upgrade:check command:

--raw: Outputs raw information.
--format=FORMAT: Output format (txt, xml, json, md).
--short: Skip arguments description.
-o, --output[=OUTPUT]: Path directory to export the .json output file.
-m, --module-path[=MODULE-PATH]: Modules path directory .
--schema1[=SCHEMA1]: Endpoint URL for the existing installation.
--schema2[=SCHEMA2]: Endpoint URL for the vanilla installation.
--vanilla-dir: Adobe Commerce vanilla installation directory.
--min-issue-level: Minimum issue level to show in report. Default is [WARNING].
--ignore-current-version-compatibility-issues: Use this option when you do not want to include known critical issues, errors and warnings in your Upgrade Compatibility Tool report.
-h, --help: Display help for that specific command. If no command is provided, list command is the default result.
-q, --quiet: Do not outputs any message while executing the command.
-v, --version: Display app version.
--ansi, --no-ansi: Enable ANSI output.
-n, --no-interaction: Do not ask any interactive question while executing the command.
-v, --vv, --vvv, --verbose: Increase verbosity of output communications. 1 for normal output, 2 for verbose output, and 3 for DEBUG output.

Output

The Upgrade Compatibility Tool exports a json file report identifying the affected code or modules, and the severity and description of the problem for every issue encountered.

To export this report into a different output folder, run:

bin/uct upgrade:check <dir> --output[=OUTPUT]

Where arguments are as follows:

<dir>: Adobe Commerce installation directory.
[=OUTPUT]: Path directory to export the .json output file.

The default path for the output folder is var/output/[TIME]-results.json.

Use the `--ignore-current-version-compatibility-issues` option

The Upgrade Compatibility Tool allows you to run the upgrade:check command with an --ignore-current-version-compatibility-issues option, so it only shows new or unknown critical issues, errors and warnings. Use this option when you do not want to include known critical issues, errors and warnings in your Upgrade Compatibility Tool report.

bin/uct upgrade:check --ignore-current-version-compatibility-issues <dir>

This applies only to PHP API validations. Core code validations are compared only with the same version.

Vanilla installation

A vanilla installation is a clean installation of a specified version tag or branch for a specific release version.

The bin/uct core:code:changes command checks if there is a vanilla instance in your system. If this is the first time using a vanilla installation, an interactive command-line question prompts you to download the vanilla project from the Adobe Commerce repository.

You can run a Upgrade Compatibility Tool command with the --vanilla-dir option to specify the Adobe Commerce vanilla installation directory.

See the Deploy vanilla instance topic for more information.

Use the `list` command

To return a list of the Upgrade Compatibility Tool available commands, run:

bin/uct list

This list commands returns the following:

-h, --help: Display help for that specific command. If no command is provided, list command is the default result.
-q, --quiet: Do not outputs any message while executing the command.
-v, --version: Display app version.
--ansi, --no-ansi: Enable ANSI output.
-n, --no-interaction: Do not ask any interactive question while executing the command.
-v, --vv, --vvv, --verbose: Increase verbosity of output communications. 1 for normal output, 2 for verbose output, and 3 for DEBUG output.

Use the `core:code:changes` command

You can compare your current Adobe Commerce installation with a clean vanilla installation to see if the core code has any modifications made to implement a new feature or customization. This validation will help estimate the effort that the upgrade will require based on those changes.

bin/uct core:code:changes <dir> <vanilla dir>

Where arguments are as follows:

<dir>: Adobe Commerce installation directory.
<vanilla dir>: Adobe Commerce vanilla installation directory.

There are some limitations when running this command:

Execute only when the project root (or main) directory is provided.
Shows a list of core modifications only.

Use the `core:code:changes` command with the `--help` option

Available --help options for the core:code:changes command:

-h, --help: Display help for that specific command. If no command is provided, list command is the default result.
-q, --quiet: Do not outputs any message while executing the command.
-v, --version: Display app version.
--ansi, --no-ansi: Enable ANSI output.
-n, --no-interaction: Do not ask any interactive question while executing the command.
-v, --vv, --vvv, --verbose: Increase verbosity of output communications. 1 for normal output, 2 for verbose output, and 3 for DEBUG output.

Version

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

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

bin/uct upgrade:check <dir> -c 2.4.3

Where:

-c, --coming-version[=COMING-VERSION]: The Adobe Commerce targeted version.

There are some limitations when running the previous command:

This parameter refers to any tag that identifies a specific version of Adobe Commerce.
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.

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:

bin/uct graphql:compare <schema1> <schema2>

Where arguments are as follows:

<schema1>: Endpoint URL for the existing installation.
<schema2>: Endpoint URL for the vanilla installation.

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

GraphQL compare command `--help` options

Available --help options for the graphql:compare command:

-h, --help: Display help for that specific command. If no command is provided, list command is the default result.
-q, --quiet: Do not outputs any message while executing the command.
-v, --version: Display app version.
--ansi, --no-ansi: Enable ANSI output.
-n, --no-interaction: Do not ask any interactive question while executing the command.
-v, --vv, --vvv, --verbose: Increase verbosity of output communications. 1 for normal output, 2 for verbose output, and 3 for DEBUG output.

Example with a list of critical issues, errors, and warnings for GraphQL

 *   [WARNING] 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.

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: Endpoint URL for the existing installation.
--schema2=SCHEMA2: Endpoint URL for the vanilla installation.
<dir>: Adobe Commerce installation directory.

Example:

bin/uct upgrade:check --schema1=https://domain1.com/graphql --schema2=https://domain2.com/graphql -c 2.4.3 <dir>

Example with a list of critical issues, errors, and warnings

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

 * [WARNING][1131] Line 23: Extending from class 'Magento\Framework\App\Action\Action' that is @deprecated on version '2.4.2'
 * [ERROR][1429] Line 103: Call method 'Magento\Framework\Api\SearchCriteriaBuilder::addFilters' that is non API on version '2.4.2'
 * [CRITICAL][1110] Line 60: Instantiating class/interface 'Magento\Catalog\Model\ProductRepository' that does not exist on version '2.4.2'

The report also includes a detailed summary:

Installed Version: the version currently installed.
Adobe Commerce Version: the version you want to upgrade to.
Running time: amount of time the analysis took to build the report (mm:ss).
Adobe Commerce core checked modules: amount of core checked modules.
Adobe Commerce core modified files: amount of core modified file.
Adobe Commerce % core modified files: percentage of core modified files.
Adobe Commerce checked modules: amount of checked modules.
Compatibility errors found: amount of compatibility errors.
Compatibility warnings found: amount of compatibility warnings.
Compatibility critical errors found: amount of compatibility critical errors.
GraphQL critical errors found: amount of GraphQL critical 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.

See the Error message reference topic for more information.

Example of a general summary report

 ------------------------------------- -------
  Installed version                    2.4.2
  Adobe Commerce version               2.4.3
  Running time                         0m:48s
  Core files checked                   0
  Core files modified                  0
  % of files modified                  0.00
  Checked modules                      14
  Compatibility errors found           109
  Compatibility warnings found         0
  Compatibility critical errors found  0
  GraphQL critical errors found        0
  GraphQL warnings found               0
  Total errors found                   109
  Total warnings found                 0
  Total critical errors found          0
  Complexity score                     218
 ------------------------------------- -------

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

Run Upgrade Compatibility Tool via PHPstorm plugin

You can run the Upgrade Compatibility Tool with a run configuration via the PHPstorm plugin. See the Upgrade Compatibility Tool Run Configuration topic for more information.

Troubleshooting

Empty output

The M2_VERSION is the target Adobe Commerce version you want to compare to your Adobe Commerce instance.

If after running this command:

bin/uct upgrade:check INSTALLATION_DIR -c M2_VERSION

The only output is Upgrade compatibility tool:

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:

php -d memory_limit=-1 /bin/uct upgrade:check INSTALLATION_DIR -c M2_VERSION

Use the upgrade:check command

Recommendations to use the upgrade:check command

Use the --help option

Output

Use the --ignore-current-version-compatibility-issues option

Vanilla installation

Use the list command

Use the core:code:changes command

Use the core:code:changes command with the --help option

Version

GraphQL schema compatibility verification

GraphQL compare command --help options

Example with a list of critical issues, errors, and warnings for GraphQL

Full report

Example with a list of critical issues, errors, and warnings

Example of a general summary report

Run Upgrade Compatibility Tool via PHPstorm plugin

Troubleshooting

Empty output

Use the `upgrade:check` command

Recommendations to use the `upgrade:check` command

Use the `--help` option

Use the `--ignore-current-version-compatibility-issues` option

Use the `list` command

Use the `core:code:changes` command

Use the `core:code:changes` command with the `--help` option

GraphQL compare command `--help` options