Contact Us 1-800-596-4880

Configuring Mule Stack Traces

This version of Mule reached its End of Life on May 2, 2023, when Extended Support ended.

Deployments of new applications to CloudHub that use this version of Mule are no longer allowed. Only in-place updates to applications are permitted.

MuleSoft recommends that you upgrade to the latest version of Mule 4 that is in Standard Support so that your applications run with the latest fixes and security enhancements.

Mule does not display all stack traces by default. When Mule does show stack traces, it filters out some internal class references from to produce a more readable output.

You can control Mule stack trace behavior in two ways:

  • Use command-line arguments

  • Set properties in Mule Studio

Use Command-Line Arguments

Use -M-DpropertyName with the following command-line arguments to control the behavior of stack traces:

  • mule.verbose.exceptions - If set to true, Mule shows filtered stack traces.

  • mule.stacktrace.filter - A comma-separated list of packages and/or classes to remove from the stack traces, which are matched using string.startsWith().

These arguments are available for Mule developers and administrators to use while troubleshooting. They are not intended for use by end users.

Set Properties in Anypoint Studio

In Studio, you can set the properties specified above to instruct Mule to provide stack traces and to filter out packages or classes to remove. To adjust these settings:

  1. Select Run > Run Configurations…​

  2. Define the properties to specify the behavior you want.

In the example below, the mule.verbose.exceptions property is set to true.

Studio-config-stacktrace

Obtain the Stack Trace and Thread Dump

Follow these steps to troubleshoot Mule if it stops and you need more information to find the cause:

  1. Identify the Mule process ID (MULE_PID).

  2. Retrieve the thread dump.

  3. Retrieve the heap dump if the Mule server throws an Out Of Memory error: java.lang.OutOfMemoryError: Java heap space

Identify the Mule process ID

To identify the Mule process ID, use the Unix/Linux ps command, or execute the jps command from the terminal. The jps tool ships with the JDK used to run Mule. For example, a line containing MuleContainerBootstrap, ApplicationDeployer, or similar identifies the Mule process.

Retrieve the Thread Dump

Use the jstack tool, which is available in modern JDKs, to retrieve the thread dump:

jstack -l MULE_PID > filename.tdump

Retrieve the Heap Dump

Retrieve the heap dump if the Mule server throws an out of memory error: java.lang.OutOfMemoryError: Java heap space

The Oracle JVM provides a JVM modifier to gather this information. You must restart the Mule server after applying this change and reproduce the out of memory error one more time.

To apply this modifier to the JVM that Mule uses, set the following parameters in Mule’s /conf/wrapper.conf file to automatically trigger the creation of a heap dump:

wrapper.java.additional.<n>=-XX:+HeapDumpOnOutOfMemoryError
wrapper.java.additional.<n+1>=-XX:HeapDumpPath=path/to/dumps

When you set the parameters, change <n> to a number that follows the sequence in wrapper.conf.

By default, Mule includes the HeapDumpOnOutOfMemoryError property, but it does not define a path for heap dumps.

If no path is defined for a heap dump, the file is created in the directory where the java process was launched. The heap dump file is then generated as java_pid<pid>.hprof.<unique number>.