See other Articles

10 Steps to Upgrade your MuleSoft Applications to Java 17 and Mule Runtime 4.9+
9
336
Introduction
In the first quarter of 2024, MuleSoft announced that customers upgrade their applications to Java 17 to adapt to Java’s long-term-support (LTS) release cadence, which will be supported by Mule 4.6 runtime.
Benefits to upgrading to Java 17 includes enhanced memory management, security, and general improved performance. Similarly, since third party vendors will also discontinue using Java 8, it is important to upgrade mule apps to Java 17 since doing otherwise will impact MuleSoft product stack. Support for Java 8 will also discontinue in March 2025.
Prerequisites
Any Mule project
Anypoint Studio
Java Runtime 17 (JRE 17)
Mule Runtime 4.9+ (Mule 4.9+)
Step 1: Understand the Impact of Java 17
Compatibility matrix:
Mule 4.4 and below: Java 8 & 11
Mule 4.6: Java 8, 11, and 17
Mule 4.9: Requires Java 17
Support timelines:
Java 8/11 ends Mar 2025 (4.8 Edge), Aug 2025 (4.6 LTS)
Anypoint Studio 7.21+ uses Java 17 by default.
Step 2: Review Current Setup and Plan the Upgrade
Make sure to list all the connectors, modules, and dependencies you are currently using, along with their current versions. This way, if you ever need to roll back or just want to see how far behind you are from the latest versions.
Before jumping into the upgrade, it is important to have a clear plan. This helps avoid surprises and ensures a smooth transition across environments.
Inform the desire for upgrade to stakeholders.
Define upgrade timeline and milestones.
Allocate time for local, QA, UAT, and prod validation.
Design rollback and recovery plan.
Setup post-upgrade performance/log monitoring.
Step 3: Validate Connector or Module Compatibility
All Anypoint connectors and modules are currently Java 17 compatible. The list of all Java 17 compatible connectors and their versions are available here.
There are two (2) ways to validate if your connector is compatible to Java 17. It can be via Anypoint Studio or Anypoint Exchange.
In Anypoint Studio:
Open your Mule project in Anypoint Studio.
Right click the Mule project.
Hover to Mule and click Java 17 Module Compatibility.
Wait for few seconds then check Problems tab in the console.
You should get a confirmation like "All modules are Java 17 compatible."
In Anypoint Exchange:
Login to your Anypoint Platform.
Go to the navigation bar and click Exchange.
In the search bar, type the name of the module or the connector (i.e. "Salesforce Connector - Mule 4").
Click and open the asset.
Click View versions and you would see the compatible Java versions for that asset.
Step 4: Check the Java Runtime and Mule Runtime of Anypoint Studio
Open your Mule project in Anypoint Studio.
Right click the Mule project.
Go to Build Path > Configure Build Path > Libraries tab.
Look for "JRE System Library".
If the version is not 17, proceed to Step 5.
Look for "Mule Server".
If the version is not 4.9, proceed to Step 6.
If everything is aligned, you may skip Step 5 and Step 6.
Step 5: Install and set Java 17 in Anypoint Studio
Install the Java 17 in your machine.
Windows:
Download the JDK
Go to the official Oracle JDK download page or use an OpenJDK distribution like Adoptium Temurin.
Download the Windows x64 installer or ZIP version.
Install Java
Run the installer and follow setup instructions.
If using the ZIP version, extract it to a location.
Set Environment Variables
Open System Properties > Advanced > Environment Variables
Find JAVA_HOME under System Variables (or create a new one if it does not exist) and set the value to the JDK installation path
Add %JAVA_HOME%\bin to the Path variable
Check java version in command prompt:
java -version
macOS:
You can use Homebrew to install Java 17:
brew install openjdk@17
Configure the JRE 17 in Anypoint Studio.
Go to Preferences > Java > Installed JREs > Execution Environment and click on JavaSE-17. If Java 17 is properly installed, the studio should be able to detect it.
Click Apply and Close.
Restart your Anypoint Studio (if needed).

Step 6: Install and set Mule Runtime 4.9 in Anypoint Studio
Open your Anypoint Studio.
Go to Help tab and click Install New Software.
Type and search for Mule Server.
Choose Mule Server Runtime 4.9.5 EE.
Click Next until you finish the installation.
Restart your Anypoint Studio (if needed).
Step 7: Update Mule Runtime and Maven Plugin
The earliest version for Mule Runtime and Maven Plugin is 4.6.0 and 4.1.0 respectively.
Open your Mule project in Anypoint Studio.
Open your pom.xml file.
Update app.runtime tag under properties tag.
<properties>
<app.runtime>4.9.0</app.runtime>
<mule.maven.plugin.version>4.5.0</mule.maven.plugin.version>
<munit.version>2.3.14</munit.version>
</properties>
Open your mule-artifact.json file.
Update the value of minMuleVersion key.
{
"minMuleVersion": "4.6.0"
}
Step 8: Update Connectors and Modules
Open your Mule project in Anypoint Studio.
Right click the Mule project.
Go to Manage Dependencies > Manage Modules.
You would see the current version of your modules. If there is a blue dot beside the version, it means that it is not the latest version.
Click the Check for updates icon, then Update all dependencies to latest icon.
Once updated, click Apply and Close.
Restart your Anypoint Studio (if needed).
If properly configured, the application should be successfully deployed in studio.

Step 9: Update API Policies
Deployment policies and API proxies depend on Java and are therefore needed to be upgraded. MuleSoft will provide updated versions of Mule Gateway included policies to be Java 17 compatible. Your Mule app should adjust to these policies accordingly.
Updating Automated Policies:
Go to API Manager and go Automated Policies.
Select the latest version of the selected policies
On Rule of Application
To apply policy to all runtimes, select All runtimes and click Save
To apply included policies to Mule Gateways only:
Select Mule gateways only.
In Java Versions, you can select All Java versions or Choose specific Java Versions.
Click Save.
Updating Custom Automated Policies:
In API Manager, go to Automated Policies.
Upgrade required extensions, connectors, and custom policies to Java 17.
Ensure any custom connectors or Anypoint connectors are upgraded (refer to respective guides).
Configure Java 17 locally and package the custom policy.
Republish the custom policy to Exchange.
Apply the new version compatible with Java 17, ensuring the latest definition is applied. If not, update it.
Updating API-Level Policies:
Navigate to API Administration > {API Name} > Policies > Add a Policy.
Apply the relevant policy for each API level.
When configuring, select the latest version of the included policy.
Under Method & Resource Conditions, choose either:
Apply configuration to all API methods & resources, or
Apply configuration to specific API methods & resources.
Click Apply to save changes.
Updating Custom API-Level Policies:
Follow the same steps as with Included Policies.
Upgrade all required extensions and connectors to be compatible with Java 17 (as mentioned earlier).
Ensure Java 17 is configured locally.
Upgrade and package the custom policy.
Republish the updated policy to Exchange.
Apply the new policy to a Java 17-compatible API instance.
For more information about upgrading policies, click here.
Step 10: Update CI/CD Pipeline-related files
Open your Mule project in Anypoint Studio.
Open your pom.xml file.
Find your CloudHub configuration and add the following tags:
releaseChannel: Set the name of the release channel used to select the Mule image. Supported values are NONE, EDGE, and LTS. By default, the value is set to EDGE. If the selected release channel doesn’t exist, an error occurs.
javaVersion: Set the Java version used in the deploy. Supported values are 8 and 17. By default, the value is set to 8. If the selected Java version doesn’t exist, an error occurs.
Open your pipeline files, and update the maven and java version.
Note: Mule Maven plugin versions 3.0.0, 3.1.0, 3.1.1, 3.1.2, 3.1.3, 3.1.4, 3.1.5, 3.1.6, 3.1.7, and 3.8.3 are deprecated. Check the latest versions in this link.
Conclusion
As MuleSoft's no. 1 value is Trust, they continue to align with the current industry by adopting to Java's Long-term-support release model with regular updates of the Java version. Therefore, they encourage their partners and customers to upgrade their applications and environment to be Java 17 compatible.
Upgrading not only ensures compatibility with future MuleSoft releases but also helps avoid potential security risks, deprecated plugin issues, and unsupported third-party libraries. It is a proactive step that strengthens stability, maintainability, and performance across your integration stack.