Out of memory errors in Pega are one of those production issues that can be difficult to diagnose without the right tools. A heap dump gives you a snapshot of the JVM memory at the moment of failure – everything you need to find the culprit.
Here is how to generate one and what to do with it.
Step 1 – Configure JVM to Generate Heap Dump Automatically
The first thing to do before any out of memory error occurs is tell the JVM to generate a heap dump file automatically when it happens. You configure this in the setenv.bat file on Windows or the equivalent shell script on Linux, found in your Tomcat bin directory.
Add two JVM settings. The first tells the JVM to generate a heap dump on out of memory error. The second – optional but useful – specifies the exact file path where the dump should be written. Create a dedicated folder for this so the file is easy to find.
Without these settings, you will have no heap dump to analyse when things go wrong. Add them before any problem occurs.
Step 2 – Reproduce the Error and Locate the File
Once the out of memory error occurs, the JVM generates an hprof file in your specified location. The filename includes the Java process ID. This file can be several gigabytes depending on your heap size configuration, so plan your storage accordingly.
Check your Catalina log file to confirm the out of memory error occurred – you will see the Java heap space message there. Then verify the hprof file was created in your dump path location.
Step 3 – Analyse With Eclipse Memory Analyzer
Download Eclipse Memory Analyzer (MAT) from their official website. It is a free tool specifically built for this purpose.
One important note – MAT is a Java application. It needs a JDK or JRE installed on the machine where you run it. If you are on a machine without one, install JDK first.
Also – and this catches people out – if your heap dump file is large (say 4GB), MAT itself needs enough heap space to load and parse it. Open the MAT configuration file and increase the maximum heap allocation before launching. 8GB is a reasonable starting point for a 4GB dump. Without this adjustment, MAT will throw its own out of memory error while trying to open your file.
Step 4 – Identify the Root Cause
Once the dump is loaded, use the Leak Suspects report. MAT analyses the object graph and identifies which objects are consuming the most memory.
What you are looking for is the thread and the object chain that led to the excessive memory consumption. Expand through the suspect objects – you will see things like ArrayList, clipboard implementations, page list properties. Keep following the parent object chain until you reach something recognisable in your Pega application context – a property name, a page list, a rule set reference.
In the example from this video, tracing the parent chain revealed a PXResults page list property that had been appended to in a loop without any page removal. Ten thousand iterations, no cleanup – classic out of memory cause.
That is the kind of clarity a heap dump gives you. Not just “out of memory error occurred” but exactly which rule, which page, which property caused it.
Watch the Full Walkthrough
In the video below I walk through the complete process – configuring JVM settings, triggering and capturing a heap dump, loading it into MAT and tracing the object chain to identify the exact activity responsible for the memory issue.
Heap dump analysis is a skill most Pega developers never develop. But if you are working on performance issues or production out of memory incidents, it is one of the most valuable tools in your debugging toolkit.
