ÃÛ¶¹ÊÓƵ

DocumentationCommerceCommerce on Cloud Guide

[PaaS only]{class="badge informative" title="Applies to ÃÛ¶¹ÊÓƵ Commerce on Cloud projects (ÃÛ¶¹ÊÓƵ-managed PaaS infrastructure) and on-premises projects only."}

Upgrade Commerce version

Last update: Tue Jul 15 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Admin
  • Developer

You can upgrade the ÃÛ¶¹ÊÓƵ Commerce code base to a newer version. Before upgrading your project, review the System requirements in the Installation guide for the latest software version requirements.

Depending on your project configuration, your upgrade tasks may include the following:

  • Update the .magento/services.yaml file with new versions for MariaDB (MySQL), OpenSearch, RabbitMQ, and Redis for compatibility with new ÃÛ¶¹ÊÓƵ Commerce versions.
  • Update the .magento.app.yaml file with new settings for hooks and environment variables.
  • Upgrade third-party extensions to the latest supported version.
TIP
Before beginning an upgrade or a patching process, create an active branch from the Integration environment and check out the new branch to your local workstation. Dedicating a branch to the upgrade or the patch process helps to avoid interference with your work in progress.
recommendation-more-help

  • For Pro projects, you must submit an ÃÛ¶¹ÊÓƵ Commerce Support ticket to install or update services in Staging and Production environments only.

  • Indicate the service changes needed, include your updated .magento.app.yaml and services.yaml files, and state the PHP version in the ticket. For self-service changes to PHP version, extensions, or environment settings, see PHP settings in Application configuration.

  • For changes to a live Production environment (Pro only), a minimum of 48 hours notice is required. This allows the Cloud infrastructure team sufficient time to marshal resources and conduct a secure upgrade. The notice period begins when the Infrastructure team acknowledges the request and schedules the upgrade, excluding weekends. For example, to have service upgrades completed on a Monday, an acknowledgement of the scheduled upgrade must be received by Wednesday. During peak demand periods, it might take more time to process your request.

style
shade-box

Configuration files

Before upgrading the application, you must update your project configuration files to account for changes to the default configuration settings for ÃÛ¶¹ÊÓƵ Commerce on cloud infrastructure or the application. The latest defaults can be found in the .

composer.json

Before upgrading, always check that the dependencies in the composer.json file are compatible with the ÃÛ¶¹ÊÓƵ Commerce version.

To update the composer.json file for ÃÛ¶¹ÊÓƵ Commerce version 2.4.4 and later**:

  1. Add the following allow-plugins to the config section:

    code language-json 
    
"config": {
   "allow-plugins": {
      "dealerdirect/phpcodesniffer-composer-installer": true,
      "laminas/laminas-dependency-plugin": true,
      "magento/*": true
   }
},

  2. Add the following plugin to the require section:

    code language-json 
    "require": {
    "magento/composer-root-update-plugin": "^2.0.3"
},

  3. Add the following component to the extra:component_paths section:

    code language-json 
    "extra": {
   "component_paths": {
      "tinymce/tinymce": "lib/web/tiny_mce_5"
   },
},

  4. Save the file. Do not commit or push changes to your branch yet.

  5. Continue with the upgrade process.

Project backup

We recommend creating a backup of your project before an upgrade. Use the following steps to back up your Integration, Staging, and Production environments.

To back up your integration environment database and code:

  1. Create a local backup of the remote database.

    code language-bash 
    magento-cloud db:dump
    note note
    NOTE
    The magento-cloud db:dump command runs the command with the --single-transaction flag, which allows you to back up your database without locking the tables.

  2. Back up code and media.

    code language-bash 
    php bin/magento setup:backup --code [--media]

    Optionally, you can omit [--media] if you have a large number of static files that are already in source control.

To back up your Staging or Production environment database before deploying:

  1. Use SSH to log in to the remote environment.

  2. Create a database dump. To choose a target directory for the DB dump, use the --dump-directory option.

    code language-bash 
    vendor/bin/ece-tools db-dump

    The dump operation creates a dump-<timestamp>.sql.gz archive file in your remote project directory. See Back up database.

Application upgrade

Review the service versions information for the latest software version requirements before upgrading your application.

To upgrade the application version:

  1. On your local workstation, change to your project directory.

  2. Set the version constraint for the target upgrade version. This step is only necessary if the target version is outside the existing constraint.

    code language-bash 
    composer require-commerce "magento/magento-cloud-metapackage":">=CURRENT_VERSION <NEXT_VERSION" --no-update
    note note
    NOTE
    You must use the version constraint syntax to successfully update the ece-tools package. You can find the version constraint in the composer.json file for the version of the you are using for the upgrade.

  3. Update your composer.json file with the core Commerce upgrade version.

    code language-bash 
    composer require-commerce magento/product-enterprise-edition 2.4.8 --no-update

  4. If you’re using B2B, update your composer.json file with the supported version for Commerce.

    code language-bash 
    composer require-commerce magento/extension-b2b 1.5.2 --no-update

  5. Update project dependencies.

    code language-bash 
    composer update

  6. Review the patches that are currently applied:

    • If there are any patches installed in the m2-hotfixes directory, submit an ÃÛ¶¹ÊÓƵ Commerce Support ticket and work with ÃÛ¶¹ÊÓƵ Commerce Support to verify which patches can still be applied to the new version. Remove the non-applicable patch(es) from the m2-hotfixes directory.

    • If there are any [Quality Patches] applied in the .magento.env.yaml file, verify whether they can still be applied to the new version. Remove the non-applicable patch(es) from the QUALITY_PATCHES section of the .magento.env.yaml file.

    Method 1: Verify the applicable versions in the Quality Patches release notes

    Method 2: View available patches and status

    Method 3: Search for patches

  7. Add, commit, and push code changes.

    code language-bash 
    git add -A
    code language-bash 
    git commit -m "Upgrade"
    code language-bash 
    git push origin <branch-name>

    git add -A is required to add all changed files to source control because of the way Composer marshals base packages. Both composer install and composer update marshal files from the base package (magento/magento2-base and magento/magento2-ee-base) into the package root.

    The files that Composer marshals belong to the new version of ÃÛ¶¹ÊÓƵ Commerce, to overwrite the outdated version of those same files. Currently, marshaling is disabled in ÃÛ¶¹ÊÓƵ Commerce, so you must add the marshaled files to source control.

  8. Wait for deployment to complete.

  9. Verify the upgrade in your Integration, Staging, or Production environment by using SSH to log in and check the version.

    code language-bash 
    php bin/magento --version

Upgrade extensions

Review your third-party extension and module pages in Marketplace or other company sites and verify support for ÃÛ¶¹ÊÓƵ Commerce and ÃÛ¶¹ÊÓƵ Commerce on cloud infrastructure. If you must upgrade any third-party extensions and modules, ÃÛ¶¹ÊÓƵ recommends working in a new integration branch with your extensions disabled.

To verify and upgrade your extensions:

  1. Create a branch on your local workstation.

  2. Disable your extensions as needed.

  3. When available, download extension upgrades.

  4. Install the upgrade as documented by the third-party documentation.

  5. Enable and test the extension.

  6. Add, commit, and push the code changes to the remote.

  7. Push to and test in your integration environment.

  8. Push to the Staging environment to test in a pre-production environment.

ÃÛ¶¹ÊÓƵ strongly recommends upgrading your Production environment before including the upgraded extensions in your site launch process.

NOTE
When you upgrade your application version, the upgrade process updates to the latest version of the Fastly CDN module automatically.

Troubleshoot upgrade

If the upgrade failed, you receive an error message in the browser indicating that you cannot access your storefront or the Admin panel:

There has been an error processing your request
Exception printing is disabled by default for security reasons.
  Error log record number: <error-number>

To resolve the error:

  1. On your local workstation, change to your project directory.

  2. Use SSH to log in to the remote environment.

    code language-bash 
    magento-cloud ssh

  3. Open the ./app/var/report/<error number> file.

  4. Examine the logs and determine the source of the issue.

  5. Add, commit, and push code changes.

    code language-bash 
    git add -A && git commit -m "Fixed deployment failure" && git push origin <branch-name>
7c2b03ac-000c-497d-aba3-2c6dc720a938