Contact Us 1-800-596-4880

Feature Flagging Mechanism

Mule runtime engine incorporates a feature flagging mechanism that enables Mule applications to change the behavior of the Mule instance depending on the required minimum Mule version. This feature ensures backward compatibility because it allows 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.

The feature flagging mechanism is automatic. For each Mule application deployed to a Mule instance, Mule determines which features are enabled or disabled based on the application’s minimum Mule version configured in the application descriptor file (mule-artifact.json) of the Mule app.

By default, Mule runtime engine disables any new features or bug fixes that aren’t backward compatible with Mule applications running in earlier Mule versions. However, it is possible to manage the feature flags configured for each Mule application or all applications running in the same Mule instance.

Understanding minMuleVersion

If your deployment was rejected because of minMuleVersion, set it to the target runtime’s version or earlier, keeping the patch at .0 unless you need a backported fix (see Adopting a Backported Bug Fix (Advanced)). Don’t set it to the exact patch of the runtime you built or scaffolded with.

minMuleVersion declares the minimum runtime feature set that a Mule application requires. Conceptually, this corresponds to the minor number in Semantic Versioning. Mule 4 follows Semantic Versioning 2.0.0. Anypoint Studio and Anypoint Code Builder use this value when scaffolding a new application.

How the Runtime and Tools Check minMuleVersion

minMuleVersion isn’t only a feature-flag selector. The runtime, and other tools that work with a Mule artifact, compare its minMuleVersion against a target version using the full major.minor.patch. If the artifact’s minMuleVersion is later than the target, it’s rejected.

The most visible case is deployment. The runtime refuses to deploy an application whose minMuleVersion is later than the running runtime, and reports that the application requires a later runtime version. For example, an application with minMuleVersion=4.12.2 doesn’t deploy on a 4.12.1 runtime, even though the two only differ in patch. To check the version of the target runtime in CloudHub, CloudHub 2.0, Runtime Fabric, or a server managed by Runtime Manager, check the environment or instance details in Runtime Manager. On a standalone on-premises server, run ./mule -version or check the startup log.

The same comparison also happens outside the deployment cycle. Any tooling that reads a Mule artifact without deploying it applies the same check. For example, a service that introspects an application’s flows to list its triggers compares the artifact’s minMuleVersion exactly as deployment does. So does Anypoint Exchange when it extracts metadata as you publish an asset. Over-declaring minMuleVersion can therefore cause an artifact to be rejected by such tooling even when you aren’t deploying it.

This comparison is patch-sensitive by design. That’s what makes the backported bug fixes described in Adopting a Backported Bug Fix (Advanced) possible. Raising the patch of minMuleVersion is how an application opts into a backported bug fix.

Choosing the Value

Set minMuleVersion to the earliest Mule version whose feature set your application needs, not the latest patch of whatever runtime you happened to build or scaffold with. Declaring a later version than necessary is called over-declaring, and it can prevent an otherwise-compatible runtime or tool from accepting the application.

Setting minMuleVersion to an earlier version has a trade-off too: It disables any feature or bug fix enabled by default between the new value and the version the application previously declared. Choose the earliest version whose behavior your application relies on, not an arbitrarily early one.

Adopting a Backported Bug Fix (Advanced)

The patch component of minMuleVersion (the third number, for example, the 2 in 4.12.2) only matters for one corner case: a bug fix backported into a patch release instead of shipping with the next minor version. This typically results from an escalated product request. The Feature Flags Reference table documents these cases. Most flags become available at a minor release, but a few become available at a patch release, for example, mule.tx.error.when.timeout, available since Mule 4.6.1.

Like every entry in that table, a backported bug fix is disabled by default, so an application relying on the preexisting behavior isn’t affected by upgrading the runtime. Enabling it is a deliberate opt-in.

On an on-premises Mule instance, the recommended way to opt in to a backported fix (or any flag) is to configure it explicitly through a system property, as described in Configure Feature Flags for the Mule Instance, rather than by bumping the patch component of minMuleVersion. Raising the patch changes every flag available since that patch at once, including ones you didn’t intend to adopt, and it also tightens the compatibility check described in How the Runtime and Tools Check minMuleVersion.

Only set a patch-level minMuleVersion when all these conditions are true:

  • The application depends on a specific backported fix.

  • The deployment target doesn’t support a system-property override.

  • MuleSoft Support has directed you to do so.

Otherwise, leave the patch at .0.

For the full list of fields in mule-artifact.json, including minMuleVersion, see Application Descriptor Reference (mule-artifact.json).

Configure Feature Flags for a Mule Application

To configure feature flags for a Mule application, change the minMuleVersion value in the mule-artifact.json file of your app. With this configuration, the Mule instance runs the application using all features and bug fixes that were released to that particular version. The instance disables features and bug fixes that are active by default in later Mule versions.

For example, you can run a Mule application in Mule 4.5.0 instructing the Mule instance to apply only the features that don’t change core functionality up to Mule 4.1.0:

Example mule-artifact.json file
{
  "minMuleVersion": "4.1.0"
}
This example intentionally uses an earlier version, 4.1.0, to illustrate selecting an earlier feature set. It’s not a recommended value for a new application. See Understanding minMuleVersion.

Configure Feature Flags for the Mule Instance

An alternative way to configure feature flags is by using system properties. In this case, you can enable or disable each one of the available feature flags. However, configuring feature flags through system properties applies the changes at the Mule instance level, so all applications deployed to this Mule instance behave according to the configured feature flags.

Note that this configuration is compatible with on-premise deployments only because you cannot configure system properties in other deployment targets.

For example, you can configure a Mule 4.5.0 instance to enable and disable specific features for all applications running on this instance:

Example wrapper.conf file
…
wrapper.java.additional.999=-DHONOUR_RESERVED_PROPERTIES_PROPERTY=true
wrapper.java.additional.1000=-DCOMPUTE_CONNECTION_ERRORS_IN_STATS_PROPERTY=false

Feature Flags Reference

The following table shows the available feature flags, a description of their functionality, the Mule version in which the flag became available, the earlier minor version releases that enable the flag by default, and the issue ID in which the change was implemented:

Feature Flag Description

mule.batch.fixed.aggregator.transaction.record.buffer

When enabled, batch aggregators with fixed size aggregators commit only when a full block is processed.

Available Since

  • 4.4.0

  • 4.3.0-20210304

  • 4.2.2-20210304

Enabled by Default Since

  • Not enabled by default in any Mule version

Issue ID

  • MULE-19218

mule.compute.connection.errors.in.stats

When enabled, connection errors are computed as part of alerts triggering.

Available Since

  • 4.4.0

  • 4.3.0-20210304

Enabled by Default Since

  • 4.4.0

Issue ID

  • MULE-19020

mule.enable.default.errorhandler.not.rollback.incorrect.tx

When enabled, the default error handler added by the Runtime doesn’t roll back a transaction if it doesn’t correspond to have this roll back made.

Available Since

  • 4.5.0

  • 4.4.0-20211227

  • 4.3.0-20211222

Enabled by Default Since

  • 4.5.0

Issue ID

  • MULE-19919

mule.dw.remove_shadowed_implicit_inputs

When enabled, DataWeave removes implicit inputs when a variable with the same name is declared at the root level.

Available Since

  • 4.5.0

  • 4.4.0-20211026

Enabled by Default Since

  • 4.4.0

Issue ID

  • DW-893

mule.enable.policy.isolation

When enabled, Mule manages extensions imported by a policy in complete isolation from the extensions imported by the Mule application. Also, validations prevent the use of explicit configurations that the application declared as part of the policy initialization.

Available Since

  • 4.4.0

  • 4.3.0-20210622

Enabled by Default Since

  • 4.4.0

Issue ID

  • MULE-19226

mule.enable.profiling.service

When enabled, the Runtime profiling capabilities become available.

Available Since

  • 4.4.0

Enabled by Default Since

  • Not enabled by default in any Mule version

Issue ID

  • MULE-19588

mule.entityResolver.failOnFirstError

When enabled, the Mule XML DSL parser fails when deploying an application that declares a schema that cannot be located. Otherwise, the parser fails if the application also makes use of the namespace to which such a schema is bound.

Available Since

  • 4.4.0

Enabled by Default Since

  • 4.4.0

Issue ID

  • EE-7827

mule.force.runtime.profiling.consumers.enablement

When enabled, profiling consumers implemented by the Runtime are enabled by default.

Available Since

  • 4.5.0

  • 4.4.0-20220221

Enabled by Default Since

  • Not enabled by default in any Mule version

Issue ID

  • MULE-19967

mule.dw.handle_splitter_exception

When enabled, DataWeave correctly handles internal exceptions while splitting a payload, preventing subsequent serialization errors.

Available Since

  • 4.4.0

Enabled by Default Since

  • 4.4.0

Issue ID

  • DW-383

mule.honour.reserved.properties

When enabled, reserved properties such as app.name can’t be overridden by global properties (overrides are ignored).

Available Since

  • 4.4.0

  • 4.3.0-20220221

Enabled by Default Since

  • 4.3.0

Issue ID

  • MULE-17659

mule.honourErrorMappingsWhenPolicyAppliedOnOperation

When enabled, the operation policy’s error resolution is ignored. Therefore, the error mappings of the processor on which the policy is applied are set successfully.

Available Since

  • 4.5.0

  • 4.4.0-20220722

  • 4.3.0-20220725

Enabled by Default Since

  • 4.5.0

Issue ID

  • W-11147961

mule.detailedCompositeRoutingExceptionLog

When enabled, AbstractForkJoinRouter-based processors, such as Parallel For Each and Scatter-Gather routers, now show detailed error information for their failed routes.

Available Since

  • 4.5.0

  • 4.4.0-20220622

Enabled by Default Since

  • 4.5.0

Issue ID

  • W-10965130

mule.parallelForeach.flattenMessage

When enabled, if the items to iterate over on a parallel-foreach scope are messages (such as the output of an operation that returns Result objects), they are flattened in a way that is consistent with what the foreach scope does.

Available Since

  • 4.5.0

  • 4.4.0-20220124

  • 4.3.0-20220124

Enabled by Default Since

  • 4.5.0

Issue ID

  • MULE-20067

mule.setVariable.WithNullValue

When enabled, the Set Variable component creates a variable even if its value is null.

Available Since

  • 4.4.0

  • 4.3.0-20210622

Enabled by Default Since

  • 4.4.0

Issue ID

  • MULE-19443

mule.startExtensionComponentsWithArtifactClassloader

When enabled, extensions are only able to load exported resources from the deployable artifacts (application, policy, domain).

Available Since

  • 4.4.0

  • 4.3.0-20211026

Enabled by Default Since

  • 4.4.0

Issue ID

  • MULE-19815

mule.transformer.toString.transformIteratorElements

When enabled, managed cursor iterators transformed to strings show the representation of the elements instead of generic value org.mule.runtime.core.internal.streaming.object.-ManagedCursorIteratorProvider$ManagedCursorIterator@.

Available Since

  • 4.4.0

Enabled by Default Since

  • 4.4.0

Issue ID

  • MULE-19323

mule.suppress.mule.exceptions

When enabled, error suppression occurs. This feature prevents components such as the Web Service Consumer connector and the Until Successful scope from reporting errors outside their namespaces.

Example of an error log extract for a connectivity error at the Web Service Consumer (HTTP:CONNECTIVITY is being suppressed):

Error type : WSC:INVALID_WSDL
Caused by  : HTTP:CONNECTIVITY

Suppressed errors are treated as underlying causes that can also be matched by On Error handlers.

Available Since

  • 4.4.0-20220922

Enabled by Default Since

  • Enabled by default in every Mule version

Issue ID

  • W-11308645

mule.support.native.library.dependencies

When enabled, if an application accesses a native library, the rest of its declared native libraries are also loaded. This prevents errors like UnsatisfiedLinkError when the accessed native library depends on another native library. Libraries must be declared at the sharedLibraries configuration following the dependency order, meaning that if library A depends on library B, then A must be declared first. Declaring the native libraries at a domain is also supported.

Available Since

  • 4.5.0

  • 4.4.0-20230417

Enabled by Default Since

  • 4.5.0

Issue ID

  • W-11855052

mule.rethrowExceptionsInIdempotentMessageValidator

When enabled, internal exceptions are rethrown instead of throwing a general MULE:DUPLICATE_MESSAGE when processing an event in the idempotent-message-validator.

Available Since

  • 4.5.0

Enabled by Default Since

  • 4.5.0

Issue ID

  • W-11529823

com.mulesoft.dw.xml_reader.honourMixedContentStructure

When this property is set to true, DataWeave retains a mixed-content structure instead of grouping text with mixed content into a single text field.

Available Since

  • 4.5.0

Enabled by Default Since

  • 4.5.0

Issue ID

  • W-11071481

ENFORCE_ERROR_TYPES_VALIDATION

When enabled, error types validations are enforced, even for error handlers/components that aren’t being referenced. This feature isn’t configurable by system property.

Available Since

  • 4.5.0

Enabled by Default Since

  • 4.5.0

Issue ID

  • MULE-19879

mule.disable.attribute.parameter.whitespace.trimming

When enabled, the runtime trims whitespaces from parameter values defined at the attribute level in the DSL.

Available Since

  • 4.5.0

Enabled by Default Since

  • 4.5.0

Issue ID

  • MULE-19803

mule.disable.pojo.text.parameter.whitespace.trimming

When enabled, the runtime trims whitespaces from CDATA text parameter of pojos in the DSL.

Available Since

  • 4.5.0

Enabled by Default Since

  • 4.5.0

Issue ID

  • MULE-20048

mule.enforce.expression.validation

When enabled, expression validations are enforced for targetValue, not allowing a literal value.

Available Since

  • 4.5.0

Enabled by Default Since

  • 4.5.0

Issue ID

  • MULE-19987

mule.enforce.dw.expression.validation

When enabled, expression validations are enforced for all DataWeave expressions.

Available Since

  • 4.5.0

Enabled by Default Since

  • 4.5.0

Issue ID

  • MULE-19967

mule.disable.registryBootstrapOptionalEntries

When enabled, optional attribute in entries in a registry-bootstrap.properties are ignored.

Available Since

  • 4.5.0

Enabled by Default Since

  • 4.5.0

Deprecated Since

  • 4.9.0, the optional attribute in entries is no longer supported

Issue ID

  • W-10736301

mule.disable.applyObjectProcessor

When enabled, org.mule.runtime.core.privileged.registry.ObjectProcessor implementations aren’t applied on objects registered into the SimpleRegistry.

Available Since

  • 4.5.0

Enabled by Default Since

  • 4.5.0

Issue ID

  • MULE-11737

mule.deployment.validateAppModelWithRegionClassloader

When enabled, the application model is validated with the region classloader. When disabled, it is validated with the application classloader.

Available Since

  • 4.5.0

Enabled by Default Since

  • 4.5.0

Issue ID

  • W-10808757

mule.suppress.mule.exceptions

When enabled, error suppression happens. This affects, for example, the Web Service Consumer connector and the Until Successful scope that always reports errors from their corresponding namespaces (MULE and WSC). Suppressed errors are treated as underlying causes.

Available Since

  • 4.5.0

  • 4.4.0-202210

Enabled by Default Since

  • Enabled by default in every Mule version

Issue ID

  • W-11308645

mule.foreachRouterRejectsMapExpressions

When enabled, the 'foreach' router generates an IllegalArgumentException if the collection expression evaluates to a java.util.Map.

Available Since

  • 4.5.0

Enabled by Default Since

  • 4.5.0

Issue ID

  • W-12207110

mule.honour.insecure.tls.configuration

When enabled, the insecure TLS configuration is honored even if there are fields of the TrustStore configured.

Available Since

  • 4.5.0

Enabled by Default Since

  • 4.5.0

Issue ID

  • W-10822938

mule.transaction.sink.index

When enabled, flux sinks are cached using index as part of the key. If a sink is already in use, a new sink is created.

Available Since

  • 4.4.0

Enabled by Default Since

  • Enabled by default in every Mule version

Issue ID

  • W-12128703

mule.enable.policy.context.parallel.scopes

When enabled, a new (Source) Policy Context is created for the execution of parallel scopes: ParallelForeach, ScatterGather, and Async.

Available Since

  • 4.5.0

  • 4.4.0-202306

Enabled by Default Since

  • 4.5.0

Issue ID

  • W-13509911

mule.put.trace.id.and.span.id.in.mdc

When enabled, the trace ID and span ID are added to the MDC when available.

Available Since

  • 4.5.0

Enabled by Default Since

  • Not enabled by default in any Mule version

Issue ID

  • W-12979787

mule.enable.mule.specific.tracing.information

When enabled, the ancestor-mule-span-id value is added in the trace state when a span is propagated.

Available Since

  • 4.5.0

Enabled by Default Since

  • Not enabled by default in any Mule version

Issue ID

  • W-13215870

mule.disableJmx.for.commons.pool2

When enabled, MBeans aren’t registered for commons-pool2.

Available Since

  • 4.6.0

Enabled by Default Since

  • 4.6.0

Issue ID

  • W-12422473

mule.disable.scheduler.logging

When enabled, the Scheduler doesn’t log exceptions.

Available Since

  • 4.6.0

Enabled by Default Since

  • 4.6.0

Issue ID

  • W-13881167

mule.tx.error.when.timeout

When enabled, an error is thrown when a local or XA transaction reach timeout. This error can be handled using error handling.

Available Since

  • 4.6.1

Enabled by Default Since

  • 4.6.1

Issue ID

  • W-14608096

mule.disableXmlSdkImplicitConfigurationCreation

When enabled, implicit configuration for the XML SDK isn’t created.

Available Since

  • 4.7.0

Enabled by Default Since

  • 4.7.0

Issue ID

  • W-10634129

mule.enable.xml.sdk.mdc.reset

When enabled, the MDC context resets after XML SDK operation is executed.

Available Since

  • 4.8.0

  • 4.7.1

  • 4.6.4

  • 4.4.0-20240522

Enabled by Default Since

  • 4.8.0

Issue ID

  • W-15206528

mule.unsupportedExtensionsClientRunAsync

When enabled, org.mule.runtime.extension.api.client.ExtensionsClient deprecated methods (executeAsync(String, String, OperationParameters) and execute(String, String, OperationParameters)) throw an UnsupportedOperationException.

Available Since

  • 1.8.0

Enabled by Default Since

  • 4.8.0

Issue ID

  • W-15399821

ENFORCE_IMPORT_TARGET_SAME_TYPE

When enabled, the root element of import targets are validated to be the same as the importing configuration.

Available Since

  • 4.8.0

Enabled by Default Since

  • 4.8.0

Issue ID

  • W-15509819

mule.honour.persisted.flow.state

When enabled, flows honor the state configured in flows.deployment.properties when restarting the app, regardless of the initial state.

Available Since

  • 4.8.0

Enabled by Default Since

  • 4.8.0

Issue ID

  • W-15750334

mule.ntlm.avoid.send.payload.on.type1

When enabled, body contents aren’t sent on NTLM type 1 requests. This saves resources by not sending a payload that is never consumed (the server rejects the payload until the dance is completed).

Available Since

  • 4.9.0

  • 4.8.4

  • 4.6.12

Enabled by Default Since

  • 4.9.0

Issue ID

  • W-17107281

mule.forkJoin.completeChildContextsOnTimeout

When enabled, the processors that perform fork and join work (currently, Scatter-Gather and Parallel For Each routers) complete the child event contexts when a timeout occurs.

Available Since

  • 4.10.0

  • 4.9.2

  • 4.6.14

  • 4.4.0-20250217

Enabled by Default Since

  • 4.10.0

Issue ID

  • W-16941297

mule.repeatableStreaming.bytes.eagerRead

When enabled, the read methods of bytes repeatable streams return immediately with any available data. If disabled, they don’t return until the requested len is fully read. Set this property to true to process SSE events over HTTP as they arrive instead of buffering them.

Available Since

  • 4.10.0

  • 4.9.7

  • 4.6.20

Enabled by Default Since

  • Not enabled by default in any Mule version

Deprecated Since

  • 4.12.0, this is configurable on streaming configuration. Use the bytes.eagerRead property instead.

Issue ID

  • W-18716253

mule.disable.optimised.notification.handler.dynamic.resolution.update.based.on.delegate

When disabled, dynamic resolution of notification handling doesn’t occur after the Mule artifact is initialized. This can cause race conditions that affect monitoring metrics.

Available Since

  • 4.10.0

Enabled by Default Since

  • Not enabled by default in any Mule version

Issue ID

  • W-16828516

mule.redeliveryPolicy.encode.secureHash

When enabled, the encrypted payload is encoded in hexadecimal format when no Expression ID is specified.

Available Since

  • 4.11.0

  • 4.10.1

  • 4.9.11

Enabled by Default Since

  • 4.11.0

Issue ID

  • W-18584560

mule.forcefulShutdown.raiseCancelledError

When enabled, events cancelled during a forceful shutdown raise a MULE:CANCELLED error instead of MULE:UNKNOWN. Dynamic configuration creation attempts during shutdown also raise a MULE:CANCELLED error instead of MULE:UNKNOWN.

Available Since

  • 4.11.0

  • 4.10.1

  • 4.9.11

  • 4.6.24

Enabled by Default Since

  • 4.11.0

Issue ID

  • W-19648397

mule.untilSuccessful.retryOnCriticalError.disallow

When enabled, events aren’t retried if a MULE:CRITICAL error occurs within an until-successful scope.

Available Since

  • 4.11.0

  • 4.10.1

  • 4.9.11

  • 4.6.24

Enabled by Default Since

  • 4.11.0

Issue ID

  • W-19648397

mule.batch.record.exceptions.disallow

When enabled, batch processing uses batch errors instead of step exceptions. The DataWeave exception-based bindings Batch::getFirstException(), Batch::getLastException(), Batch::failureExceptionForStep(String), and Batch::getStepExceptions() are replaced by their error-based equivalents Batch::getFirstError(), Batch::getLastError(), Batch::failureErrorForStep(String), and Batch::getStepErrors().

Available Since

  • 4.11.0

  • 4.10.2

  • 4.9.12

  • 4.6.25

Enabled by Default Since

  • 4.12.0

Issue ID

  • W-19607093

mule.netty.redirect.filterSensitiveHeaders

When enabled, the Authorization, Proxy-Authorization, and Expect headers are removed from redirected requests to a different host. This applies only when the HTTP Service implementation is Netty.

Available Since

  • 4.11.0

Enabled by Default Since

  • 4.12.0

Issue ID

  • W-20903125

mule.propagate.objectStore.customization.to.policies

When enabled, policies use the object store implementation configured for the application. This enables alternative implementations, such as Object Store v2, to be used by policies.

Available Since

  • 4.11.1

  • 4.10.3

  • 4.9.13

  • 4.6.26

Enabled by Default Since

  • 4.12.0

Issue ID

  • W-19607093

mule.enable.inline.tls.context.initialization

When enabled, inline TLS contexts invoke their lifecycle initialization method, ensuring inline TLS contexts are fully initialized before use.

Available Since

  • 4.11.3

  • 4.9.16

  • 4.6.29

Enabled by Default Since

  • Not enabled by default in any Mule version

Issue ID

  • W-20038933

mule.flowStop.parallel.enable

When enabled, all Mule flows are stopped in parallel rather than sequentially when a Mule application is stopped. This prevents delays caused by in-flight events in one flow from delaying the shutdown of other flows.

Available Since

  • 4.12.0

  • 4.11.1

  • 4.9.14

  • 4.6.27

Enabled by Default Since

  • 4.12.0

Issue ID

  • W-21228085

mule.serialize.message.in.cache

When enabled, ee:cache persists only the Message instead of the full Event. Java customizations for ee:cache aren’t supported, including custom implementations of cachingStrategy-ref, keyGenerator, responseGenerator, and eventCopyStrategy. After this feature flag is enabled, it can’t be disabled because the format of persisted data is updated.

Available Since

  • 4.12.0

Enabled by Default Since

  • 4.12.0

Issue ID

  • W-21549211

mule.enable.byteBuddy.objectCreation

When enabled, the object factories are created with Byte Buddy instead of CGLIB.

Available Since

  • 4.4.0-202203

  • 4.3.0-202203

Enabled by Default Since

  • 4.4.0

Deprecated Since

  • 4.5.0, ByteBuddy is mandatory

Issue ID

  • W-10672687

ENFORCE_BATCH_AGGREGATOR_VALIDATION

When enabled, batch:aggregator validations are enforced.

Available Since

  • 4.12.0

Enabled by Default Since

  • 4.12.0

Issue ID

  • W-21549351

ENFORCE_POLICY_PROXY_VALIDATION

When enabled, http-policy:proxy completeness validations are enforced.

Available Since

  • 4.12.0

Enabled by Default Since

  • 4.12.0

Issue ID

  • W-21549351