--- schema_version: "1" id: c0d30a3a288cfee9e841ece0371e40f7d8db4724e1973289614bf86f1919a1a5 title: Upgrading Mule Runtime Engine (Versions 4.x to 4.n) collection: mulesoft version: current locale: ja-jp portal_url: https://docs.salesforce.com/mulesoft/current/ja-jp/release-notes/mule-runtime/updating-mule-4-versions.md canonical_url: https://docs.mulesoft.com/jp/release-notes/mule-runtime/updating-mule-4-versions source_site: docs.mulesoft.com content_type: documentation content_hash: f12b5ee6d76d0c2b58f528a5ebcefeecca2b3f10b9a3fe6180c53fe496907dcc description: MuleSoft Documentation Site latest: true --- # Upgrading Mule Runtime Engine (Versions 4.x to 4.n) To upgrade your current Mule instance to a later release of Mule runtime engine (version 4.x), you must follow some best practices. The following steps and recommendations help you to: - Upgrade your standalone Mule instances. - Upgrade your on-premises Mule instances managed through Runtime Manager. - Change the Mule version used to build your Mule applications, if necessary. To change the Mule runtime engine version of your CloudHub workers, you need to use the [runtime version drop-down box](https://docs.mulesoft.com/cloudhub/deploying-to-cloudhub#runtime-tab) in the application settings deployment configuration page. ## [](#ensuring-mule-application-compatibility)Ensuring Mule Application Compatibility When you create a Mule application, you select the Mule runtime engine version that your application is intended to run on. This is the target Mule version of an application. Because Mule runtime engine uses semantic versioning (MAJOR.MINOR.PATCH), Mule applications are: - Rarely compatible between _major_ releases (3.9.3 to 4.1.0, for example). - Potentially compatible between _minor_ releases (4.1.0 to 4.2.0, for example). - Fully compatible between _patch_ releases (4.1.4 to 4.1.5 for example). Note that Mule provides a feature flagging mechanism that enables Mule applications to change the behavior of the Mule instance depending on the minimum Mule version (`minMuleVersion`). This feature ensures backward compatibility because it enables Mule applications to continue working on later Mule runtime versions, while new Mule applications can benefit from the latest bug fixes implemented in the Mule instance. For details, see [Feature Flagging Mechanism](https://docs.mulesoft.com/mule-runtime/latest/feature-flagging). Read the [release notes](https://docs.mulesoft.com/jp/release-notes/mule-runtime/mule-esb) for the Mule runtime engine version that you want to upgrade to and verify if you must make any compatibility changes to your Mule applications. MuleSoft recommends executing a regression test cycle to validate compatibility between minor releases. For Mule 4.5 and later, the version naming convention for CloudHub, CloudHub 2.0, and Runtime Fabric changes following the schema for the new release channels, Edge and Long-term Support (LTS). _Major\[numeric\] . Minor\[numeric\] . Patch\[numeric\] : Build\[numeric\] Channel\[e for edge, nothing for LTS\]_ Here are examples of the version numbers: - Edge: 4.5.0:1e - Edge: 4.6.0:1e - LTS: 4.6.0:1 In the case of Standalone (On-Premises), the Mule runtime versioning changes from date-based, for example, `4.4.0-20230317` to semVer as: _Major\[numeric\] . Minor\[numeric\] . Patch\[numeric\]_ Here are examples of the version numbers: - 4.5.1 - 4.5.2 - 4.5.3 See [Edge and LTS Releases for Mule](https://docs.mulesoft.com/jp/release-notes/mule-runtime/lts-edge-release-cadence). ### [](#changing-the-target-mule-version-of-your-mule-application)Changing the Target Mule Version of your Mule Application In case you need to change your Mule application’s target Mule version, follow these steps: 1. [Download the desired Mule runtime engine](https://docs.mulesoft.com/studio/studio-update-sites#mule-runtimes-for-anypoint-studio-update-site) in Anypoint Studio so that you can select that version in the IDE. 2. For every application that you upgrade: 1. [Import the application](https://docs.mulesoft.com/studio/import-export-packages#importing-projects-to-studio) to Anypoint Studio as a Mule project. 2. During the import process remember to change the target Mule version by selecting it from the **Server Runtime** menu. ![updating mule versions 415](/mulesoft/current/ja-jp/release-notes/_images/mule-runtime/updating-mule-versions-415.png) 3. Make any other changes necessary to ensure compatibility with the Mule version you are transitioning to. 4. [Export your project](https://docs.mulesoft.com/studio/import-export-packages#exporting-projects-from-studio) as a Mule Deployable Archive (`.jar` file). 5. Edit the `pom.xml` file to make the `muleVersion` property value match the target Mule version. After you have successfully built the Mule Deployable Archives (`.jar` files) with the new target Mule version, and you have applied any other necessary changes to ensure compatibility, you can move on to upgrading the corresponding Mule runtime engine instances. ## [](#upgrading-a-standalone-mule-instance)Upgrading a Standalone Mule Instance Use the Mule upgrade tool to automate the upgrade process of your local Mule instances. Visit [Mule upgrade tool](https://docs.mulesoft.com/mule-runtime/latest/mule-upgrade-tool) for installation and usage instructions. Optionally, you can also perform a completely manual update of your Mule instances. To ensure less downtime and easier backups during manual upgrades, first install the new Mule runtime engine on a separate server from that on which your current Mule runtime engine is installed. That way you can set everything up and only then initiate the new Mule instance and decouple the previous one.

If you are upgrading Mule in the same server or virtual machine, ensure that you remove the Mule service or daemon before you install the new Mule runtime engine as a service.
### [](#steps-to-manually-upgrade-the-mule-instance)Steps to Manually Upgrade the Mule Instance 1. From the Customer Portal, download the Mule runtime engine version you want to upgrade to. 2. If you run Mule as a service, install the new Mule version on a different server or virtual machine: - `$MULE_HOME\bin\mule.bat install` on Windows systems - `$MULE_HOME/bin/mule install` on Linux/Unix systems 3. Download a new copy of your license from the Customer Portal and install it on the new Mule instance (see [Installing an Enterprise License](https://docs.mulesoft.com/on-premises/latest/installing-an-enterprise-license) for instructions). 4. If you have custom configurations in your previous Mule instance (for example, if you defined a different maximum heap size in the `wrapper.conf` file), replicate these settings in the new Mule instance. 5. [Run your new Mule instance](https://docs.mulesoft.com/on-premises/latest/starting-and-stopping-mule-esb#running-mule) to verify that your installation is working as expected. 6. After considering possible negative impact, you can shut down your previous Mule instance at this point. 7. If you set environment variables such as `MULE_HOME` or `PATH`, verify that they point to the new Mule runtime engine’s installation path. 8. Deploy your applications to your new Mule instance. ## [](#mulerunvers)Upgrading an On-Premises Mule Instance Managed Through Runtime Manager Use the Mule upgrade tool to automate the upgrade process of your local Mule instances. Visit [Mule upgrade tool](https://docs.mulesoft.com/mule-runtime/latest/mule-upgrade-tool) for installation and usage instructions. Optionally, you can also perform a completely manual update of your on-premises Mule instances. To ensure less downtime and easier backups, first install the new Mule runtime engine on a separate server from that on which your current Mule runtime engine is installed. That way you can set everything up. Shut down the previous Mule instance and only then initiate the new Mule instance. To manually migrate following these steps, you must have the [Runtime Manager Agent](https://docs.mulesoft.com/jp/runtime-manager/runtime-manager-agent) installed. ### [](#steps-to-manually-upgrade-the-mule-instance-2)Steps to Manually Upgrade the Mule Instance 1. Go through steps 1 through to 5 of the previous section, [Upgrading a Standalone Mule Instance](#upgrading-a-standalone-mule-instance). 2. Copy the following three files from `/conf` from your previous Mule instance into the same folder on the new Mule instance: - `mule-agent.yml` - `mule-agent.jks` - `truststore.jks` and/or `anypoint-truststore.jks` 3. Copy the `mule-agent-plugin` folder from `/server-plugins` from your previous Mule instance into the same folder on the new Mule instance. 4. Shut down the previous Mule instance. 5. Open a terminal window and navigate to the `/bin` directory of your new Mule instance. 6. Run the following command: amc\_setup -U This command installs the latest version of the Runtime Manager Agent on your new Mule instance, ensuring compatibility. The files you copied from your previous Mule instance hold all of the configuration information to register the new Mule instance on Runtime Manager. Even when you’re installing your new Mule version on another server or VM, the copied configuration files should suffice to smoothly transition the Mule instance’s identity on Runtime Manager. If your previous Mule instance has apps deployed through Runtime Manager, there’s no need to manually copy them, as they automatically upload to your new Mule instance. This process automatically redeploys the applications to the new instance. If your previous Mule instance has apps that were manually deployed, you need to manually redeploy them.

Applications must be running and showing as Started in Runtime Manager. This process does not migrate stopped Applications.
7. At this point, your Mule instance is upgraded to the desired Mule version. Updating the target Mule version of your deployed applications is optional. If you decide to do so, then you must also: 1. Follow the steps in [Changing the Target Mule Version of your Mule Application](#changing-the-target-mule-version-of-your-mule-application). 2. Find the application on the **Applications** tab on Runtime Manager and click **Choose File** to [upload](https://docs.mulesoft.com/jp/runtime-manager/managing-deployed-applications#updating-your-application) the new Mule Deployable Archive (`.jar` file). ### [](#considerations-about-clusters)Considerations About Clusters After you complete the manual upgrade steps for your on-premises Mule instance, copy the `mule-cluster.properties` file from folder `/.mule` in the previous Mule instance to the same folder in the new Mule instance. If the `.mule` folder does not exist in the new Mule instance, create the folder and then copy the file. Zero downtime cannot be guaranteed when upgrading the Mule runtime engine version of your Runtime Manager clusters. At some point during the upgrade, the cluster is in a mixed state, with coexisting nodes running two different Mule versions. This might lead to incompatible communication protocols between Hazelcast instances. When such errors occur, every node in the cluster must be shut down to proceed with the upgrade. ## [](#upgrade-the-mule-runtime-version-in-a-runtime-manager-server-group)Upgrade the Mule Runtime Version in a Runtime Manager Server Group Follow these steps to upgrade the Mule version in a Runtime Manager server group: 1. Go to Anypoint Runtime Manager. 2. Switch to the corresponding environment. 3. Select **Servers** in the navigation menu. 4. Select the server group to update. 1. In the server group dashboard, select the **Servers** tab and select the server to upgrade. 2. In the actions dropdown menu, select **Shutdown**. 3. Repeat the previous two steps for each server in your server group. 5. Open a terminal in the local machine that hosts your Mule instance. 6. If your Runtime Manager agent version is earlier than 2.2.0, upgrade to the latest version. Go to the current Mule Home directory and run the following commands: `cd ${MULE-4.1.5_HOME}/bin` `cp ~/Downloads/agent-setup-2.4.20.zip .` `unzip agent-setup-2.4.20.zip` `./amc_setup -U` 7. Go to the target directory for the new Mule runtime version and install it: `cd ${MULE-4.3.0_DIRECTORY}` `cp ~/Downloads/mule-ee-distribution-standalone-4.3.0.zip .` `unzip mule-ee-distribution-standalone-4.3.0.zip` 8. Install the latest agent version: `cd mule-enterprise-standalone-4.3.0/bin` `cp ~/Downloads/agent-setup-2.4.20.zip .` `unzip agent-setup-2.4.20.zip` `./amc_setup -I` `rm ../conf/mule-agent.yml` 9. Copy the following files from the previous Mule runtime `/conf` directory to the new Mule runtime `/conf` directory: - All YAML files (`*.yml`) - All keystore files (`*.jks`) 10. Confirm that the DNS configured in `mule-agent.yml` has the following values: websocket.transport: consoleUri: wss://runtime-manager.anypoint.mulesoft.com:443/mule authenticationProxy: endpoint: https://data-authenticator.anypoint.mulesoft.com 11. If you installed domains in your previous Mule instance, copy those domains to your new Mule instance: `cp -R ${MULE-4.1.5_HOME}/domains${MULE-4.3.0_HOME}/domains` 12. Start Mule: `cd ${MULE-4.3.0_HOME}/bin` `./mule start` 13. Go to Runtime Manager to confirm that your Mule applications are deployed and displayed as **Running**. ## [](#upgrading-from-mule-4-2-or-4-1-to-mule-4-3-or-later)Upgrading from Mule 4.2 or 4.1 to Mule 4.3 or Later If you are upgrading from Mule 4.2.x or 4.1.x to Mule 4.3.x or later Mule 4 releases, take the following actions: - If no custom threading settings are applied (either through `scheduler-pools.conf` or directly in the Mule app), then no action is required. - If custom threading configurations are applied, test your Mule applications using the default configuration. Because of the UBER pool strategy and other performance updates implemented in Mule 4.3, you might not need custom threading configurations. - If tests confirm that a custom configuration is still necessary, a problem might exist with resource management in the application, one of the application dependencies, or the Mule instance. ## [](#see-also)See Also - [Mule Upgrade Tool](https://docs.mulesoft.com/mule-runtime/latest/mule-upgrade-tool) - [Mule Standalone Installation](https://docs.mulesoft.com/on-premises/latest/runtime-installation-task) - [Runtime Manager](https://docs.mulesoft.com/jp/runtime-manager/) - [Known Issues](https://help.salesforce.com/s/issues)